Document ambient and point light sources

documentation/levels/file_formats.md

@@ -36,14 +36,15 @@ linked pages for more details.
 
 ## Materials
 
-As mentioned above, material data for objects is not read from their `.blend`
-files. This is also true for static level geometry. Instead, all materials are
-defined in `.skm.yaml` files located in the `assets/materials/` directory. These
-YAML files specify textures, colors, as well as other more complex RDP/RSP
-settings. They are currently used at export time to generate display lists using
-libultra. Since one of the goals of this project is to build a
-library-independent abstraction layer, it is currently not a priority to
-document the format of these files.
+As mentioned above, most material data for objects is not read from their
+`.blend` files. This is also largely true for
+[static level geometry](./level_objects/static.md) (see linked page for
+exceptions). Instead, all materials are defined in `.skm.yaml` files located in
+the `assets/materials/` directory. These YAML files specify textures, colors, as
+well as other more complex RDP/RSP settings. They are currently used at export
+time to generate display lists using libultra. Since one of the goals of this
+project is to build a library-independent abstraction layer, it is currently not
+a priority to document the format of these files.
 
 When exporting a level, only the name of each material is used. The actual
 material information is looked up in the `.skm.yaml` files using the name. This

documentation/levels/level_objects/README.md

@@ -30,6 +30,7 @@ easy.
 
 See the pages below for details on specific level objects.
 
+* [@ambient](./ambient.md)
 * [@anim](./anim.md)
 * [@ball_catcher](./ball_catcher.md)
 * [@ball_launcher](./ball_launcher.md)
@@ -45,10 +46,10 @@ See the pages below for details on specific level objects.
 * [@fizzler](./fizzler.md)
 * [@location](./location.md)
 * [@pedestal](./pedestal.md)
+* [@point_light](./point_light.md)
 * [@room](./room.md)
 * [@security_camera](./security_camera.md)
 * [@signage](./signage.md)
 * [@static](./static.md)
 * [@switch](./switch.md)
 * [@trigger](./trigger.md)
-* More... (TODO)

documentation/levels/level_objects/ambient.md

@@ -0,0 +1,31 @@
+# @ambient
+
+A 3D box whose vertex colors allow ambient lighting to be calculated for
+[static geometry](./static.md).
+
+## Name structure
+
+```
+@ambient
+```
+
+## Notes
+
+Ambient light sources are not used at runtime. Rather, they are used by the
+[tools/bake_lighting.py](../../../tools/bake_lighting.py) Blender script to
+precompute vertex colors for static geometry. This script must be run manually
+in Blender prior to exporting a level.
+
+Baked colors are chosen for a given vertex by considering the (up to) two
+closest ambient light sources. The color contribution of each found source is
+calculated by interpolating between its vertex colors based on the target's
+position. Finally, the contributions are blended based on each source's distance
+from the target. Either smooth or flat shading can be used.
+
+In order for an object to receive baked lighting, it must have a mesh whose
+material has the custom property `bakeType` set to `lit` in Blender. The
+materials in `assets/materials/materials.blend` are tagged appropriately.
+
+Instead of using this approach, it is also possible to manually assign vertex
+colors to static geometry using the `Col` color attribute layer. Ambient light
+sources just make it easier to simulate and edit lighting.

documentation/levels/level_objects/point_light.md

@@ -0,0 +1,33 @@
+# @point_light
+
+A point in space which allows omnidirectional light to be calculated for
+[static geometry](./static.md).
+
+
+## Name structure
+
+```
+@point_light
+```
+
+## Notes
+
+Point light sources are not used at runtime. Rather, they are used by the
+[tools/bake_lighting.py](../../../tools/bake_lighting.py) Blender script to
+precompute vertex colors for static geometry. This script must be run manually
+in Blender prior to exporting a level.
+
+Each point light must be defined as a
+[light object](https://docs.blender.org/manual/en/latest/render/lights/light_object.html#)
+in Blender. When baking, the effect on a given vertex is calculated based on the
+light's color, distance, angle to the target, and energy. Vertices are only
+affected by a point light source if they are within range of its closest
+[ambient light source](./ambient.md). Either smooth or flat shading can be used.
+
+In order for an object to receive baked lighting, it must have a mesh whose
+material has the custom property `bakeType` set to `lit` in Blender. The
+materials in `assets/materials/materials.blend` are tagged appropriately.
+
+Instead of using this approach, it is also possible to manually assign vertex
+colors to static geometry using the `Col` color attribute layer. Point light
+sources just make it easier to simulate and edit lighting.

documentation/levels/level_objects/room.md

@@ -1,6 +1,6 @@
 # @room
 
-A box which groups objects in a level. Used for broad phase collision and
+A 3D box which groups objects in a level. Used for broad phase collision and
 culling.
 
 ## Name structure

documentation/levels/level_objects/static.md

@@ -30,8 +30,9 @@ coodrinates, vertex colors, material information, and UV coordinates. It is not
 used for collision. Instead there are dedicated [static](./collision.md) and
 [dynamic](./dynamic_box.md) collision objects.
 
-Materials specified in Blender are only used for their name, which serves as a
-key to look up their actual data elsewhere
+With the exception of [ambient](./ambient.md) and [point](./point_light.md)
+light bake types, materials specified in Blender are only used for their
+name, which serves as a key to look up their actual data elsewhere
 (see [Level File Formats](../file_formats.md#materials)) and to denote which
 surfaces are portalable. The following material names allow portals to be placed:
 
@@ -43,7 +44,7 @@ This behavior can be overridden by using the `no_portals` argument. To accept
 portals, the geometry must also have a coplanar static collision object or be
 animated by a [bone](./anim.md) that also animates a dynamic collision object.
 
-UV coordinates are only used for materials without the `tileSizeS` and
-`tileSizeT` properties in their YAML definition. Otherwise, the
+A mesh's UV coordinates are only used if its material does not have the
+`tileSizeS` and `tileSizeT` properties in its YAML definition. Otherwise, the
 `uvtransx`/`uvtransy`/`uvtransz`, `uvrotx`/`uvroty`/`uvrotz`, and `uvscale`
 arguments can be specified to manipulate UV maps.

documentation/levels/level_objects/trigger.md

@@ -1,6 +1,6 @@
 # @trigger
 
-A 3D volume that can set [signals](../signals.md) and start
+A 3D box that can set [signals](../signals.md) and start
 [cutscenes](../cutscenes.md) in response to object collision.
 
 ## Name structure

documentation/levels/signals.md

@@ -46,10 +46,10 @@ occurs.
 
 ## Triggers
 
-[Triggers](./level_objects/trigger.md) are 3D volumes in a level that set
-signals depending on which object type enters them. Like level objects, this
-information is defined in their object name in the level's `.blend` file.
-Trigger object names are of the form:
+[Triggers](./level_objects/trigger.md) are 3D boxes in a level that set signals
+depending on which object type enters them. Like level objects, this information
+is defined in their object name in the level's `.blend` file. Trigger object
+names are of the form:
 ```
 @trigger PLAYER_CUTSCENE_NAME PLAYER_SIGNAL_NAME CUBE_CUTSCENE_NAME CUBE_SIGNAL_NAME
 ```