Regardless of the complexity of the system you create, there will always be hidden nuances that are not immediately obvious. Every time you come back to it, you need to relearn it—search through the code, data assets, and sometimes even run experiments to make sure everything works as expected.
Below, I will provide an example of documentation that saves a huge amount of time for everyone who works with this system.
Vehicle Damage & Lighting Framework
This document contains a set of rules that define how functionality should be developed and organized.
Two sets of textures exist simultaneously: intact and damaged. Each damage zone has a corresponding mask used to reveal the damaged version of the material. Each damage event must include the index or indices of the damage zones, as well as the speed and direction at the moment of impact. The direction and speed are required for spawning particles.
Each state is triggered by calling its corresponding function. Each function has an enable/disable flag. The set of lights for the ignition state is an integral part of all the others.
After taking damage in the corresponding area, all types of lights assigned to it will be turned off.
State description
This is the basic list that will be available from the start. The system allows adding or combining lighting states. All flickering scenarios are embedded in the materials. States are simply turned on and off.
Name | Required conditions | Description |
|---|
Ignition |
| This mode will forcibly turn off the “Alarm” |
|---|
Breaking | “Ignition” is turned on | Turns on the braking lights |
|---|
Reverse | “Ignition” is turned on | Turns on the reverse light |
|---|
High beam | “Ignition” is turned on | Turns on the High beam lights (In this mode, two additional spotlights are turned on) |
|---|
Emergency | “Ignition” is turned on | Emergency state is available for vehicles with special signals. It can also use animated light sources |
|---|
Alarm | “Ignition” is turned on | “Alarm” plays a flickering scenario using the “Ignition” lights, but it does not activate the “Ignition” mode itself |
|---|
It is necessary to have the ability to independently control the state of each light source. The best way to generate such masks is to use an atlas in the second UV set. For simplicity, the cell size should be 0.1. These masks will be controlled via CPD.
All methods will be contained within the vehicle lighting component of the base class. They will be accessible from any child instance. The use of light sources is still an open question.
Name | Up | FR | FL | RR | RL | i0 | i1 | i2 | i3 | i4 |
CPD Index | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
Looking at the example document, it’s easy to understand how much time it can save.
For 3D artists, it becomes clear what the structure of the second UV set should be. Every new vehicle will be created according to the described rules. There’s no need to repeatedly explain or remind these rules—just attach a link to the document to the task instead.
When adding new mechanics or modifying existing ones, it’s immediately visible which custom primitive data indices are currently in use and for what purposes. Situations where two different systems use the same indices simply become impossible.
The damage zone indices defined in the document eliminate confusion when setting up collisions and their corresponding events.
Now let’s take a moment to imagine what the process of adding another vehicle would look like without proper documentation—and, more importantly, consider the difference in time required. For people involved in building systems, the answer is obvious. However, I should note that not all studios maintain a sufficient culture of working with documentation. And if your Confluence or Notion doesn’t have a document dedicated to custom primitive data indices or stencil masks, I think that’s a strong signal that it’s time to take action.
