Skip to content

Commit c0f36aa

Browse files
greerdvgreerdv
committed
add approved shape component translation offset RFC
Signed-off-by: greerdv <[email protected]>
1 parent ce87090 commit c0f36aa

File tree

1 file changed

+103
-0
lines changed

1 file changed

+103
-0
lines changed

‎rfcs/RFC Feature - Translation Offset for Shape Components.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Translation Offset for Shape Components
2+
3+
### Summary
4+
5+
A translation offset will be added to certain shape components (primarily focusing on axis-aligned box, box, sphere and capsule), and manipulators for those shapes will be updated to take advantage of the new offset. This will remove the restriction that the shapes must be centered on the entity position, and make setting up shapes significantly easier for users.
6+
7+
### What is the relevance of this feature?
8+
9+
Shapes are often used to define regions for other components such as reflection probes or vegetation placement, and so are consumed by a very large number of other components. Currently, shapes must be centered at the position of the entity they are attached to. This can make it impossible to align a shape with a mesh or other feature on the same entity if the origin of that feature is not conveniently placed, often forcing users to add an extra entity in order to change the relative position of the shape. It also creates an awkward workflow of repeatedly switching between modifying shape dimensions and entity transforms.
10+
11+
This has led to numerous requests to make box shape components easier to adjust by allowing the faces to be moved asymmetrically. See for example
12+
13+
- [9883](https://github.com/o3de/o3de/issues/9883)
14+
- [9672](https://github.com/o3de/o3de/issues/9672)
15+
16+
### Feature design description
17+
18+
- Certain shape components (the proposal is to focus on axis-aligned box, box, sphere and capsule initially as they are the most frequently used) will have a translation offset parameter added. Other shapes can be updated over time.
19+
- All components which depend on affected shape components will be updated to handle translation offsets.
20+
- Manipulators will be added/updated to allow the offsets to be edited on the affected components. The box shape will allow faces of the box to be moved independently, as well as translating the entire shape relative to the entity. The capsule shape will allow the two ends of the capsule to be moved independently, as well as translating the entire shape.
21+
22+
### Technical design description
23+
24+
#### Internal representation and API
25+
26+
Internally, the shape components will have a new translation offset field added. Although there are various ways the new data could potentially be parameterized, this has the advantage that if it defaults to (0, 0, 0), then no existing saved data will be broken. It can still be presented to the user using some other parameterization. For example, for a `BoxShapeComponent`, the offset can be presented as independently movable faces.
27+
28+
A getter and setter for the translation offset will be added to the `ShapeComponentRequestsBus` and the `OnShapeChanged` event in `ShapeComponentNotificationsBus` updated to fire when the translation offset changes.
29+
30+
Adding the offset will increase memory usage for shape components, but the additional memory requirement will be negligible (even for a million entities with shape components, only 16MB extra would be required). It is also tiny compared to the memory required to add another entity, as is often currently necessary to work around the lack of an offset.
31+
32+
#### Dependent components
33+
34+
The following components depend on one or more shape components. All of these components will be updated to work with translation offsets as part of this work, with no expectation of work from the affected SIGs other than reviewing PRs. Unit tests will be added and manual testing conducted to minimize the risk of introducing incorrect behavior to those components.
35+
36+
| Component | Location | SIG | Notes | AA Box | Box | Caps | Comp | Cyl | Disk | Prism | Quad | Ref | Sphere | Tube |
37+
| ------------------------------------------------ | ---------------------- | ------------------ | ------- |:------:|:---:|:----:|:----:|:---:|:----:|:-----:|:----:|:---:|:------:|:----:|
38+
| GradientSurfaceDataComponent | Gems\GradientSignal | sig-content | | x | x | x | x | x | x | x | x | x | x | x |
39+
| GradientTransformComponent | Gems\GradientSignal | sig-content | | x | x | x | x | x | x | x | x | x | x | x |
40+
| ShapeAreaFalloffGradientComponent | Gems\GradientSignal | sig-content | | x | x | x | x | x | x | x | x | x | x | x |
41+
| SurfaceAltitudeGradientComponent | Gems\GradientSignal | sig-content | | x | x | x | x | x | x | x | x | x | x | x |
42+
| SurfaceDataShapeComponent | Gems\SurfaceData | sig-content | | x | x | x | x | x | x | x | x | x | x | x |
43+
| TerrainHeightGradientListComponent | Gems\Terrain | sig-content | | x | x | x | x | x | x | x | x | x | x | x |
44+
| TerrainLayerSpawnerComponent | Gems\Terrain | sig-content | | x | | | | | | | | | | |
45+
| TerrainMacroMaterialComponent | Gems\Terrain | sig-content | | x | | | | | | | | | | |
46+
| TerrainPhysicsColliderComponent | Gems\Terrain | sig-content | | x | | | | | | | | | | |
47+
| TerrainSurfaceMaterialsListComponent | Gems\Terrain | sig-content | | x | | | | | | | | | | |
48+
| SurfaceAltitudeFilterComponent | Gems\Vegetation | sig-content | | x | x | x | x | x | x | x | x | x | x | x |
49+
| SpawnerComponent | Gems\Vegetation | sig-content | | x | x | x | x | x | x | x | x | x | x | x |
50+
| BlockerComponent | Gems\Vegetation | sig-content | | x | x | x | x | x | x | x | x | x | x | x |
51+
| ShapeIntersectionFilterComponent | Gems\Vegetation | sig-content | | x | x | x | x | x | x | x | x | x | x | x |
52+
| RandomTimedSpawnerComponent | Gems\LmbrCentral | sig-content | Legacy? | x | x | | | x | x | | x | x | x | |
53+
| AudioAreaEnvironmentComponent | Gems\LmbrCentral | sig-graphics-audio | Legacy? | x | x | x | x | x | x | x | x | x | x | x |
54+
| DiffuseProbeGridComponentController | Gems\DiffuseProbeGrid | sig-graphics-audio | | | x | | | | | | | | | |
55+
| AreaLightComponentController | Gems\AtomLyIntegration | sig-graphics-audio | | x | x | x | x | x | x | x | x | x | x | x |
56+
| ReflectionProbeComponentController | Gems\AtomLyIntegration | sig-graphics-audio | | | x | | | | | | | | | |
57+
| ShapeWeightModifierComponentController | Gems\AtomLyIntegration | sig-graphics-audio | | x | x | x | x | x | x | x | x | x | x | x |
58+
| BaseColliderComponent | Gems\PhysX | sig-simulation | | x | x | x | x | x | x | x | x | x | x | x |
59+
| EditorShapeColliderComponent | Gems\PhysX | sig-simulation | | | x | x | | x | | x | x | | x | |
60+
| EditorNavigationAreaComponent | Gems\LmbrCentral | sig-simulation | Legacy? | | | | | | | x | | | | |
61+
| RecastNavigationPhysXProviderComponentController | Gems\RecastNavigation | sig-simulation | | x | | | | | | | | | | |
62+
63+
#### Debug Draw and Visibility
64+
Debug draw for the affected shape components will be updated to render the shapes in the correct location relative to their entities. The implementations of BoundsRequests::GetWorldBounds and ShapeComponentRequests::GetEncompassingAabb will be updated to ensure correct entity visibility.
65+
66+
#### Non-uniform scale
67+
68+
Some shapes are currently marked as compatible with the non-uniform scale component:
69+
70+
- Box
71+
- Quad
72+
- Polygon Prism
73+
74+
Additional care should be taken (e.g. writing extra unit tests) with the box shape to ensure that non-uniform scale is correctly applied with respect to the translation offset.
75+
76+
### What are the advantages of the feature?
77+
78+
- Users will be able to position shapes relative to their entities, removing the frequent need to create additional entities just to handle the offset.
79+
- Users will be able to set up shape components significantly more easily.
80+
81+
### What are the disadvantages of the feature?
82+
83+
- It could be a slightly worse experience if the user wants symmetrical editing. Two mouse operations or a more complex mouse operation with modifier key could be required to perform symmetrical editing. This compares to a very bad current experience of having to switch repeatedly between editing the entity transform and the shape dimensions.
84+
85+
### How will this be implemented or integrated into the O3DE environment?
86+
87+
- This proposal just updates the existing internal shape components, no further integration is necessary.
88+
89+
### Are there any alternatives to this feature?
90+
91+
- No, other then continuing with the status quo.
92+
93+
### How will users learn this feature?
94+
95+
- Through the component modes and manipulators for the affected shape components.
96+
97+
### Are there any open questions?
98+
99+
- What about rotation offsets? This would be problematic for several reasons:
100+
- Additional scope.
101+
- Can't work with shapes which current support non-uniform scale, and would be a breaking change for any existing serialized data which uses e.g. box shape with non-uniform scale.
102+
- Less requested as a feature versus translation offsets.
103+
- Should modifier keys be supported (e.g. to allow symmetrical editing)? If so, how will they be discovered?

0 commit comments

Comments
 (0)