Adding Dynamic Collisions

Something that is described as dynamic is characterized by continuous change, activity, or progress. In the context of LVD files, a "dynamic object" is a classification of an LVD object that allows game code to easily find the object and modify its associated data, such as its transform. This is commonly attributed to ground collision objects, but also extends to "item popup region" and "damage shape" objects.

Unfortunately, marking an LVD object as dynamic does not inherently enable an assigned parent model to transform it, so it is up to game code to handle it as necessary. This is the reason why a naive approach to adding new dynamic ground collision objects without custom code typically results in no effect in-game.

stage_config takes advantage of a built-in system which automatically allows a parent model to influence the transformation of a dynamic ground collision object as well as an associated "item popup region" object if one exists.

Before associating stage_config with your mod, check if the target stage already supports adding dynamic ground collision objects. Proceed with the steps for setup but exclude work on the configuration file. This may reduce the number of dependencies for your mod and simplify your workflow.

Setting Up Dynamic Collisions

1. Create or prepare the ground collision object to be marked as dynamic. The ground collision object should assume the same rest position as the target parent model.
2. Set the ground collision object's dynamic name to be that of the target parent model folder's name (e.g., ring_set).
3. Flag the ground collision object and its base as dynamic.

Supported Transformations

Ground collision detection is a two-dimensional process only. As a result, only the transformations that make sense in a two-dimensional space are supported. Unsupported transformations do not have any effect in-game.

Transformation	Axis	Supported?
Translation	X	✔️
Translation	Y	✔️
Translation	Z	❌
Rotation	X	❌
Rotation	Y	❌
Rotation	Z	✔️
Scale	X	✔️
Scale	Y	✔️
Scale	Z	❌

Parenting Dynamic Collisions to Joints

By default, the game will automatically parent the dynamic ground collision object to the first joint in the parent model's skeleton if it exists. However, a joint of choice can be specified either by name (recommended) or by index.

If you wish to parent multiple dynamic ground collision objects to multiple different joints in the same parent model, there is a required extra step involved. Due to technical decisions on the game developers' parts, a unique identifier must be appended to the dynamic name of the object to distinguish it from other dynamic objects with the same dynamic name.

The rules of this identifier are as follows:

• It must begin and end with two underscores each.
• It must contain at least one character.
• It must not contain any intermediate underscores.

An example of a valid unique identifier comes from Town and City: __VillageC__
When appended to the dynamic name: dyr_RING_lift_set__VillageC__

Configuration

Create a new key–value pair under the new_dynamic_collisions table, where the key is the internal stage name, and the value is an array of parent model names assigned to dynamic ground collision objects. Examples are given below:

[new_dynamic_collisions]
Metroid_Norfair = ["dyr_foothold_set"]

[new_dynamic_collisions]
Sonic_Greenhill = ["s68_greenhill_main", "s68_greenhill_maina"]