Area Bullet Physics engine - reeseschultz/godex GitHub Wiki
⚠️ 🔥 DISCLAIMER 🔥 ⚠️
This is a work in progress feature that was published to give the possibility to early test it. Any feedback / bug report is welcome but keep in mind that this is subject to changes according to the received feedbacks.
The Areas in games are useful to create triggers, that can be used to create mechanics like the bonfire damage system that deplete the health when the Character walks in; allow to detect the Character region pass, so it's possible to play a new song; to know when the ball, in the pinball game, touches a spring; etc...
In Godex Bullet Physics is possible to create an area by adding the BtArea component to an Entity. As you can notice, the area has the usual layer and mask properties (we already saw on the RigidBody) and some other properties relative on the overlap event.
Area Overlap event
The area has a handy mechanism to emit the overlap event: Whenever the Area enters in contact with a RigidBody, or an Area, the area attaches a component to the overlap body.
Imagine you have a bonfire 🔥, and the Character takes damage when it walks in 🤕.
You can use an Area to detect when the Character enters the bonfire, so you can setup the Area to attach the Damage component directly when the overlap occurs. The health will be depleted by the DamageSystem, you already created while implementing the weapons. So, with 0 additional code, leveraging the Area overlap mechanism, you made the bonfire inflict damages.
However, you may have different scenarios, but fortunately we can fine tune how the Area emits the event.
Overlap Event Mode
Using the Overlap Event Mode parameter, is possible to chose the behavior:
Nothing: on overlap the Area will not attach any component. This is useful when you have a System that fetches the overlaps directly from the Area.Add Component on enter: On overlap, the Area will add the defined Component. This is useful when you want to trigger the mechanism when the body enters; like on the pinball game, I used it to attach theBounchingComponentto push it away.Add component on exit: When the body finishes its overlap, the defined Component is attached.Keep component while overlap: The component is add when the overlap begins and removed when the overlap ends. This mode is perfect to code the bonfire damage mechanics.
Keep in mind that you can even attach an Event Component.
Overlap Add Component
The parameter Overlap Add Component, allow to chose which component you want the Area will spawn on overlap. The dropdown, will show the list of components that are marked as spawnable by the OverlapEventSpawner: to know more about Spawners, and know how to make your component spawnable by the OverlapEventSpawner check this.
Overlap Data
Add a component on overlap is useful, but we may need even more than that. What if we have many bonfire sizes, each with a different damage amount? No problem! We can use the Overlap Data to feed the spawned component.
The Overlap Data is a dictionary, that the spawner will use to initialize the spawned component. Each key is a variable name, while the value is simply the value the component will have.
We may need to know the Area EntityID the Character is overlapping, for example to change the bonfire colour. We can use the special keyword @entity_id as value; such keyword will be replaced with the actual EntityID of the Area (as long as the receiver variable is of type integer).
If you need to know the transform: You can define the keyword @transform, and once again it will set the Area transform (as long as the receiver variable is of type Transform).
The keywords prefixed by @ (like the above @entity_id & @transform) are a good way to save us the need to write a system that extracts those info.
Create an Area
To create an Area you need to create a new Entity and add the Components:
- TransformComponent
- BtArea
- BtRigidShape
- Mesh (Used to visualize it)
In addition you need to set the Bullet Physics Systems, though first let's quickly read about Shapes.
➡️ Next chapter Shapes