mirror of
https://github.com/mwpenny/portal64-still-alive.git
synced 2024-10-19 22:27:36 -04:00
Level object documentation around geometry and collision
* Anim * Dynamic box * Static
This commit is contained in:
Matt Penny
parent
3a99d714cf
commit
3bcf1371e9
|
|
@ -20,13 +20,12 @@ file. Reusable objects are defined in their own `.blend` files located in the
|
|||
`assets/models/` directory and then referenced from the level `.blend` files
|
||||
which use them.
|
||||
|
||||
At export time, level object data beyond position, rotation,
|
||||
etc. is generally not read from `.blend` files. Rather, objects use a naming
|
||||
convention which tells the exporter their type and parameters so information
|
||||
like the mesh and material data can be looked up elsewhere. This naming
|
||||
convention is also what hooks the objects up to code. To learn more about what
|
||||
can appear in a level and how to configure it, see
|
||||
[Level Objects](./level_objects/README.md).
|
||||
At export time, level object data beyond position, rotation, etc. is generally
|
||||
not read from `.blend` files. Rather, objects use a naming convention which
|
||||
tells the exporter their type and parameters so information like the mesh and
|
||||
material data can be looked up elsewhere. This naming convention is also what
|
||||
hooks the objects up to code. To learn more about what can appear in a level and
|
||||
how to configure it, see [Level Objects](./level_objects/README.md).
|
||||
|
||||
### Level scripting (YAML file)
|
||||
|
||||
|
|
|
|||
|
|
@ -30,12 +30,15 @@ easy.
|
|||
|
||||
See the pages below for details on specific level objects.
|
||||
|
||||
* [@anim](./anim.md)
|
||||
* [@button](./button.md)
|
||||
* [@clock](./clock.md)
|
||||
* [@collision](./collision.md)
|
||||
* [@door](./door.md)
|
||||
* [@doorway](./doorway.md)
|
||||
* [@dynamic_box](./dynamic_box.md)
|
||||
* [@location](./location.md)
|
||||
* [@room](./room.md)
|
||||
* [@static](./static.md)
|
||||
* [@switch](./switch.md)
|
||||
* More... (TODO)
|
||||
|
|
|
|||
38
documentation/levels/level_objects/anim.md
Normal file
38
documentation/levels/level_objects/anim.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
# @anim
|
||||
|
||||
An animatable bone of an armature.
|
||||
|
||||
## Name structure
|
||||
|
||||
```
|
||||
@anim ARMATURE_NAME [sound_type SOUND_TYPE_NAME]
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
| Name | Description |
|
||||
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `ARMATURE_NAME` | The name of the armature the bone is a part of |
|
||||
| `sound_type SOUND_TYPE_NAME` (optional) | If specified, `SOUND_TYPE_NAME` will play while the armature is being animated. Only the sound type of the first bone found is used. |
|
||||
|
||||
## Notes
|
||||
|
||||
Bone animations are defined using standard Blender animations which, when
|
||||
played, transform child [static geometry](./static.md) and
|
||||
[dynamic collision](./dynamic_box.md) objects. This is useful for moving walls
|
||||
and platforms. Only position and rotation can be animated.
|
||||
|
||||
Bones can be their own independent objects or part of a Blender armature, which
|
||||
allows multiple to be transformed by the same animation. Bones must have
|
||||
matching armature name arguments and not be nested in order to be animated
|
||||
together. This is due to the way animations are serialized at level export time
|
||||
and how they are played.
|
||||
|
||||
Level animations are triggered in [cutscenes](../cutscenes.md) by specifying an
|
||||
armature name and one of its animations to play. An armature can be thought of
|
||||
as a single logical level element which is updated independently of others.
|
||||
|
||||
The possible values for `SOUND_TYPE_NAME` are:
|
||||
* `LightRail`: Horizontal moving platform sound
|
||||
* `Piston`: Vertical moving platform sound
|
||||
* `Arm`: Horizontal moving wall sound
|
||||
|
|
@ -12,8 +12,8 @@ Static level collision geometry. Must be a quad.
|
|||
|
||||
| Name | Description |
|
||||
| ---------------------------- | ---------------------------------------------------------------------------------------- |
|
||||
| `transparent` (optional) | If `transparent` is specified, the `TRANSPARENT` collision layer will be added |
|
||||
| `thickness DEPTH` (optional) | If `thickness` is specified, the quad's thickness will be set to `depth` |
|
||||
| `transparent` (optional) | If specified, the `TRANSPARENT` collision layer will be added |
|
||||
| `thickness DEPTH` (optional) | If specified, the quad's thickness will be set to `depth` |
|
||||
| `CL_X` (optional) | Space-separated list of colllision layer names. Only those prefixed with `CL_` are used. |
|
||||
|
||||
## Notes
|
||||
|
|
@ -25,21 +25,21 @@ If no collision layers are specified, the defaults are `STATIC`, `TANGIBLE`, and
|
|||
`BLOCK_BALL`. The possible layers and their uses are as follows.
|
||||
|
||||
* `STATIC`: Used for portal raycasts, and by:
|
||||
* Doors
|
||||
* [Doors](./door.md)
|
||||
* Elevators
|
||||
* `TRANSPARENT`: Unused
|
||||
* `TANGIBLE`: Used to check grabbing and walking, and by:
|
||||
* Ball catchers
|
||||
* Ball launchers
|
||||
* [Button](./button.md)s
|
||||
* [Buttons](./button.md)
|
||||
* Decor
|
||||
* [Door](./door.md)s (when open)
|
||||
* Dynamic boxes
|
||||
* [Doors](./door.md) (when open)
|
||||
* [Dynamic boxes](./dynamic_box.md)
|
||||
* Elevators
|
||||
* Player
|
||||
* Portals
|
||||
* Security cameras
|
||||
* Switches
|
||||
* [Switches](./switch.md)
|
||||
* Triggers
|
||||
* `GRABBABLE`: Used to check grabbing, and by:
|
||||
* Decor
|
||||
|
|
@ -54,7 +54,7 @@ If no collision layers are specified, the defaults are `STATIC`, `TANGIBLE`, and
|
|||
* `BLOCK_BALL`: Used by:
|
||||
* Energy balls
|
||||
* Ball launchers
|
||||
* Dynamic boxes
|
||||
* [Dynamic boxes](./dynamic_box.md)
|
||||
* Elevators
|
||||
* Player
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ A sliding door which can open or close in response to a [signal](../signals.md).
|
|||
|
||||
| Name | Description |
|
||||
| -------------------------| ---------------------------------------------------------------------------------- |
|
||||
| `OPEN_SIGNAL_NAME` | The name of the signal to which will open the door when set |
|
||||
| `OPEN_SIGNAL_NAME` | The name of the signal which will open the door when set |
|
||||
| `TYPE` (optional) | The type of door. `02` for vertical sliding hatches, otherwise circular exit door. |
|
||||
|
||||
## Notes
|
||||
|
|
|
|||
18
documentation/levels/level_objects/dynamic_box.md
Normal file
18
documentation/levels/level_objects/dynamic_box.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
# @dynamic_box
|
||||
|
||||
Dynamic level collision geometry. Useful for moving platforms.
|
||||
Must be a child of an [animation bone](./anim.md).
|
||||
|
||||
## Name structure
|
||||
|
||||
```
|
||||
@dynamic_box
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
Dynamic box colliders are animated when their parent bone is.
|
||||
|
||||
If portalable [static geometry](./static.md) exists as a sibling (i.e., animated
|
||||
by the same bone), the collider will be used for portal gun projectile hits and
|
||||
take priority over any coplanar [static collision](./collision.md).
|
||||
49
documentation/levels/level_objects/static.md
Normal file
49
documentation/levels/level_objects/static.md
Normal file
|
|
@ -0,0 +1,49 @@
|
|||
# @static
|
||||
|
||||
Static level geometry. Used to generate level mesh and portal surface
|
||||
data.
|
||||
|
||||
## Name structure
|
||||
|
||||
```
|
||||
@static [no_portals] [indicator_lights SIGNAL_NAME] [uvtransx TRANS_X] [uvtransy TRANS_Y] [uvtransz TRANS_Z] [uvrotx ROT_X] [uvroty ROT_Y] [uvrotz ROT_Z] [uvscale SCALE]
|
||||
```
|
||||
|
||||
## Arguments
|
||||
|
||||
| Name | Description |
|
||||
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `no_portals` (optional) | If specified, the surface will not be considered portalable, regardless of its material name |
|
||||
| `indicator_lights SIGNAL_NAME` (optional) | If specified and the indicator light or door state material is used, it will be switched to the corresponding "active" variant when the specified signal is set |
|
||||
| `uvtransx TRANS_X` (optional) | If specified and the material has `tileSizeS` and `tileSizeT` properties, translates UV coordinates by `TRANS_X` on the X axis |
|
||||
| `uvtransy TRANS_Y` (optional) | If specified and the material has `tileSizeS` and `tileSizeT` properties, translates UV coordinates by `TRANS_Y` on the Y axis |
|
||||
| `uvtransz TRANS_Z` (optional) | If specified and the material has `tileSizeS` and `tileSizeT` properties, translates UV coordinates by `TRANS_Z` on the Z axis |
|
||||
| `uvrotx ROT_X` (optional) | If specified and the material has `tileSizeS` and `tileSizeT` properties, rotates UV coordinates by `ROT_X` degrees on the X axis |
|
||||
| `uvroty ROT_Y` (optional) | If specified and the material has `tileSizeS` and `tileSizeT` properties, rotates UV coordinates by `ROT_Y` degrees on the Y axis |
|
||||
| `uvrotz ROT_Z` (optional) | If specified and the material has `tileSizeS` and `tileSizeT` properties, rotates UV coordinates by `ROT_Z` degrees on the Z axis |
|
||||
| `uvscale SCALE` (optional) | If specified and the material has `tileSizeS` and `tileSizeT` properties, scales UV coordinates by `SCALE/tileSize` in each direction |
|
||||
|
||||
## Notes
|
||||
|
||||
Beyond the arguments listed above, static geometry is used for its vertex
|
||||
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
|
||||
(see [Level File Formats](../file_formats.md#materials)) and to denote which
|
||||
surfaces are portalable. The following material names allow portals to be placed:
|
||||
|
||||
* `concrete_modular_wall001d`
|
||||
* `concrete_modular_ceiling001a`
|
||||
* `concrete_modular_floor001a`
|
||||
|
||||
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
|
||||
`uvtransx`/`uvtransy`/`uvtransz`, `uvrotx`/`uvroty`/`uvrotz`, and `uvscale`
|
||||
arguments can be specified to manipulate UV maps.
|
||||
Loading…
Reference in a new issue