diff --git a/README.md b/README.md index 793d3e6..5945b21 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ This whole documentation repository is licensed under CC0-1.0, see the LICENSE.r Fork this repo, edit what you want, and open pull requests! -See instructions below for setting up locally. +See instructions bellow for setting up locally. The documentation source is written in reStructuredText and Markedly Structure Text, a simple and well-defined markup language. To learn about it, check out or copy-paste from: - https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html diff --git a/_static/style.css b/_static/style.css index ac8f44c..23a2b98 100644 --- a/_static/style.css +++ b/_static/style.css @@ -68,4 +68,8 @@ The minimun number of colors or backticks for a block directive is 3 (except for ::: ; this ends the tab :::: ; this ends the tab set -*/ \ No newline at end of file +*/ + +img.no-shrink { + max-width: none !important; +} \ No newline at end of file diff --git a/common/index.rst b/common/index.rst index be67068..f6582c2 100644 --- a/common/index.rst +++ b/common/index.rst @@ -17,4 +17,5 @@ Documentation not specific to a game (SM64/OoT64). :maxdepth: 1 :caption: Other: - updater/updater \ No newline at end of file + updater/updater + repo_settings/repo_settings \ No newline at end of file diff --git a/common/repo_settings/repo_settings.png b/common/repo_settings/repo_settings.png new file mode 100644 index 0000000..7e2ed6c Binary files /dev/null and b/common/repo_settings/repo_settings.png differ diff --git a/common/repo_settings/repo_settings.rst b/common/repo_settings/repo_settings.rst new file mode 100644 index 0000000..ff73126 --- /dev/null +++ b/common/repo_settings/repo_settings.rst @@ -0,0 +1,14 @@ +Repo Settings +============= + +.. image:: repo_settings.png + +Repo settings can be used to save common settings in fast64, each gamemode can support extra settings. + +.. note:: Currently only supported by SM64 + +| Supported game modes will attempt to load fast64.json from the repository folder if auto load is enabled in the file. +| Game mode specific settings can be found in the respective tabs. +| General fast64 settings and save/load operators can be found in the **Fast64** tab in the **Fast64 Global Settings** + +If you want to stop a value from being set on loading the settings, you can remove it from the json. \ No newline at end of file diff --git a/sm64/custom_commands/binary_type.png b/sm64/custom_commands/binary_type.png new file mode 100644 index 0000000..7c75fa8 Binary files /dev/null and b/sm64/custom_commands/binary_type.png differ diff --git a/sm64/custom_commands/boolean.png b/sm64/custom_commands/boolean.png new file mode 100644 index 0000000..ad8c0b7 Binary files /dev/null and b/sm64/custom_commands/boolean.png differ diff --git a/sm64/custom_commands/color.png b/sm64/custom_commands/color.png new file mode 100644 index 0000000..92807d6 Binary files /dev/null and b/sm64/custom_commands/color.png differ diff --git a/sm64/custom_commands/custom_commands.rst b/sm64/custom_commands/custom_commands.rst new file mode 100644 index 0000000..bb3c27f --- /dev/null +++ b/sm64/custom_commands/custom_commands.rst @@ -0,0 +1,328 @@ +Custom Commands (2.5.0+) +======================== + +| Custom commands are a way to define custom macros for level scripts, geolayouts and "special" collision. +| They can inherit basic properties of their owners (e.g. level empties can inherit all transforms, bones can inherit geometry, transforms (excluding scale) and layers). +| They can be exported in either binary or C. + +Example Use Cases +----------------- + +| `Lighting engine `_ + implements custom commands for lights. +| In the previous implementation of custom commands, you'd have to specify each parameter. +| Now, you can use :download:`presets! ` + +.. list-table:: + :widths: 50 50 + :header-rows: 0 + :align: center + + * - .. image:: example_lighting_engine_presets.png + - .. image:: example_lighting_engine_empty.png + +Using custom commands +--------------------- + +| You can use custom commands in object empties and bones by selecting **Custom**. + +.. list-table:: + :widths: 50 50 + :header-rows: 0 + :align: center + + * - .. image:: empty_no_preset.png + - .. image:: empty_no_preset_bone.png + +| You can then select a preset, or use the default No Preset mode. +| See `Adding new custom command presets`_ or skip to `Configuration`_. + +Adding new custom command presets +--------------------------------- + +| You can create reusable commands that can be applied across multiple objects or bones. +| To do this, go into the SM64 tab, in **SM64 General Settings**, press the add button under **Custom Commands**. +| See `Configuration`_. +| These will be saved with :doc:`Repo Settings <../../common/repo_settings/repo_settings>`! + +.. list-table:: + :widths: 33 33 34 + :header-rows: 0 + :align: center + + * - .. image:: empty_preset_edit_geo.png + - .. image:: empty_preset_edit_level.png + - .. image:: empty_preset_edit_special.png + +Configuration +------------- +Some settings are only available when creating presets. + +.. _command-name: + +**Name**: *(Exclusive to presets)* + The name that will appear in the preset dropdown + +.. _command-type: + +**Type**: + - *Level*: Commands for level scripts, shows up in empties. + - *Geo*: Commands for geometry layouts, shows up in empties and bones + - *Collision*: Commands for collision data (Special, sometimes used for warps and a few objects), shows up in empties + +.. _command: + +**Command**:: + The macro name or numeric ID of the command + +.. _skip-eval: + +**Skip Eval**: + When enabled, skip expression evaluation outside of binary mode + +Level +~~~~~ + +.. image:: empty_preset_edit_level.png + :align: left + +.. raw:: html + +
+ +.. _section: + +**Section**: (Exclusive to presets, always **Hierarchy** without a preset) + +- .. _section-hierarchy: + + *Hierarchy*: Adds before areas if parented to level, otherwise in respective area + +- .. _section-area: + + *Area*: Adds to area (errors if parented to level) + +- .. _section-level: + + *Level*: Adds to level (errors if parented to area) + +- .. _section-force-level: + + *Force to Level*: Forces addition to level even if parented to area + +Geolayout Presets +~~~~~~~~~~~~~~~~~ +.. image:: empty_preset_edit_geo.png + :align: left + +.. raw:: html + +
+ +.. _children-requirements: + +**Children Requirements**: *(Exclusive to presets)* + +- .. _children-requirements-none: + + *None*: No requirements for child nodes, can optionally have children + +- .. _children-requirements-must-have: + + *Must Have Children*: Requires at least one child node, errors otherwise (like ``GEO_SWITCH``) + +- .. _children-requirements-no-children: + + *No Children*: Errors if node has children nodes (like ``GEO_ASM``) + +.. _children-requirements-children: + +**Group Children**: + Use ``GEO_OPEN_NODE``/``GEO_CLOSE_NODE`` to group child nodes + +.. _displaylist-option: + +**Displaylist Option**: + +- .. _displaylist-option-none: + + *None*: Doesn´t inherit geometry, deform disabled for bones + +- .. _displaylist-option-optional: + + *Optional*: Can inherit geometry, if no geometry can be inherited it uses ``NULL`` or the :ref:`Displaylist Command `. + +- .. _displaylist-option-required: + + *Required*: Must inherit geometry or export will fail + +.. _displaylist-command: + +**Displaylist Command**: (Exclusive to :ref:`Displaylist Option being set to Optional `) + | Command to use when geometry can be inherted. Will add an extra displaylist argument at the end. + | This is seen in vanilla with for e.g. ``GEO_TRANSLATE_NODE``, with the displaylist variant is ``GEO_TRANSLATE_NODE_WITH_DL`` (under the hood these use the same ID) + +.. _is-animated: + +**Is Animated** + Include animation data on animation export + +Arguments +~~~~~~~~~ + +| Arguments define the parameters your custom command will include. +| In presets, you can set a name that will be displayed. The toggle to the left of the name enables its visibility in the UI, but the argument will be appended to the comman either way. +| To create a new argument, press the plus button. + +.. _`expression`: + +**Expression**: (Binary or with "Skip Eval" disabled) + Defines a basic python expression that will run on the final values being passed. Pre generated examples will not take these into accounts + + .. note:: + The expressions are limited in functionality to prevent abuse, as custom commands get loaded automatically from repo settings. + + Example: + + .. image:: eval_example.png + :align: left + + ``(round(y * 255) for y in x[:3])`` + + We are taking the final RGBA color in base 1, isolating RGB, scaling each value to 0-255 and rounding. + + .. raw:: html + +
+ + Supported builtin python functions: + ``round``, ``abs``, ``len``, ``min``, ``max``, ``sum``, ``sorted``, ``all``, ``any``, ``enumerate``, ``tuple``, ``list``, ``set``, ``dict``, ``range`` + + Additional functions: + * ``flatten(x)``: + | Flattens a nested list/tuple into a single tuple. + | ``flatten([1, 2, [3, 4]])`` -> ``[1, 2, 3, 4]`` + * ``cast_integer(value, bit_count, signed)``: + Clamps an integer to the valid range of a specific bit count and signness. + + .. math:: + Min = + \begin{cases} + -(2^{\text{bit_count} - \text{signed}}) & \text{if signed} \\ + 0 & \text{if not signed} + \end{cases} + + .. math:: + Max = 2^{\text{bit_count - signed}} - signed + +.. _binary-types: + +**Export Types**: *(Exclusive to binary)* + | Bellow the eval expression, an option for the final types is available. Each argument type has its own appropriate default type. + | These are standard 64 bit types, as in, int is 32 bit, long is 64 bit, float is 32 bit and double is 64 bit. + + .. image:: binary_type.png + +.. _common-options: + +**Common Options**: + + - **Use Relative Transformation**: + Use the local (relative to parent) transformation instead of the world transformation + - **Blender to SM64 Scale**: + Multiply by Blender to SM64 scale value + - **Inherit**: + Inherit values from owner, like transformations or geometry. + +.. _argument-types: + +.. list-table:: Types + + * - .. image:: parameter.png + :class: no-shrink + - **Parameter** + + Basic string, binary will try to evaluate this + + * - .. image:: boolean.png + :class: no-shrink + - **Boolean** + + True/false + + * - .. image:: number.png + :class: no-shrink + - **Number** + + - *Is Integer*: Whole numbers + - *Min/Max* (Preset Only): Value limits + - *Step* (Preset Only): Increment/decrement amount + + * - .. image:: color.png + :class: no-shrink + - **Color** + + Base 1 RGBA color + + - **Round to Conventional Units**: + + | Uses singular argument, each value corresponds to the bit count of R, G, B, A. + | If 0 the element is removed. + + * - .. image:: enum.png + :class: no-shrink + - **Enum** + + Dropdown selection of user defined options + + * - .. image:: translation.png + :class: no-shrink + - **Translation** + + - **Round to Conventional Units**: + + Rounds to signed 16-bit + + * - .. image:: rotation.png + :class: no-shrink + - **Rotation** + + - **Rotation Type**: + + - *Euler*: Euler rotation in degrees + - *Quaternion*: Quaternion representation + - *Axis Angle*: Axis and angle representation + + - **Rotation Order**: + + | Order to convert to. + | ZYX is the default for level objects, XYZ is the default for geolayout commands. + + * - .. image:: scale.png + :class: no-shrink + - **Scale** + + Not available in bones + + - **Round to Conventional Units**: + + Rounds to x * ``0x10000`` + + * - .. image:: matrix.png + :class: no-shrink + - **Matrix** + + 4x4 transformation matrix + + * - .. image:: layer.png + :class: no-shrink + - **Layer** + + If geometry can be inherited this is overridden + + * - .. image:: displaylist.png + :class: no-shrink + - **Displaylist** + + - **Encode to Segmented Address**: (Binary only) + Encode address with the segment of the export level's segment diff --git a/sm64/custom_commands/displaylist.png b/sm64/custom_commands/displaylist.png new file mode 100644 index 0000000..0a70c80 Binary files /dev/null and b/sm64/custom_commands/displaylist.png differ diff --git a/sm64/custom_commands/empty_no_preset.png b/sm64/custom_commands/empty_no_preset.png new file mode 100644 index 0000000..6ba90e3 Binary files /dev/null and b/sm64/custom_commands/empty_no_preset.png differ diff --git a/sm64/custom_commands/empty_no_preset_bone.png b/sm64/custom_commands/empty_no_preset_bone.png new file mode 100644 index 0000000..6db666b Binary files /dev/null and b/sm64/custom_commands/empty_no_preset_bone.png differ diff --git a/sm64/custom_commands/empty_preset_edit_geo.png b/sm64/custom_commands/empty_preset_edit_geo.png new file mode 100644 index 0000000..cb341d4 Binary files /dev/null and b/sm64/custom_commands/empty_preset_edit_geo.png differ diff --git a/sm64/custom_commands/empty_preset_edit_level.png b/sm64/custom_commands/empty_preset_edit_level.png new file mode 100644 index 0000000..bcd1c2d Binary files /dev/null and b/sm64/custom_commands/empty_preset_edit_level.png differ diff --git a/sm64/custom_commands/empty_preset_edit_special.png b/sm64/custom_commands/empty_preset_edit_special.png new file mode 100644 index 0000000..3ea846d Binary files /dev/null and b/sm64/custom_commands/empty_preset_edit_special.png differ diff --git a/sm64/custom_commands/enum.png b/sm64/custom_commands/enum.png new file mode 100644 index 0000000..776d402 Binary files /dev/null and b/sm64/custom_commands/enum.png differ diff --git a/sm64/custom_commands/eval_example.png b/sm64/custom_commands/eval_example.png new file mode 100644 index 0000000..31f4321 Binary files /dev/null and b/sm64/custom_commands/eval_example.png differ diff --git a/sm64/custom_commands/example_lighting_engine.json b/sm64/custom_commands/example_lighting_engine.json new file mode 100644 index 0000000..2a611cf --- /dev/null +++ b/sm64/custom_commands/example_lighting_engine.json @@ -0,0 +1,311 @@ +{ + "version": 1.0, + + "sm64": { + "custom_cmds": [ + { + "name": "Point Light", + "cmd_type": "Geo", + "str_cmd": "GEO_SCENE_LIGHT", + "skip_eval": false, + "children_requirements": "ANY", + "group_children": false, + "dl_option": "NONE", + "is_animated": false, + "args": [ + { + "name": "Type", + "show_as_preset": false, + "arg_type": "PARAMETER", + "value_type": "CHAR", + "signed": true, + "defaults": { + "parameter": "2" + } + }, + { + "name": "RGB", + "show_as_preset": true, + "arg_type": "COLOR", + "eval_expression": "(round(y) * 255 for y in x[:3])", + "value_type": "CHAR", + "signed": true, + "round_to_sm64": false, + "defaults": { + "color": [ + 1.0, + 1.0, + 1.0, + 1.0 + ] + } + }, + { + "name": "Quadratic falloff", + "show_as_preset": true, + "arg_type": "NUMBER", + "value_type": "CHAR", + "signed": true, + "is_integer": true, + "step": 0, + "min": 0, + "max": 255, + "defaults": { + "value": 0 + } + }, + { + "name": "Linear falloff", + "show_as_preset": true, + "arg_type": "NUMBER", + "value_type": "CHAR", + "signed": true, + "is_integer": true, + "step": 0, + "min": 0, + "max": 255, + "defaults": { + "value": 0 + } + }, + { + "name": "Constant falloff", + "show_as_preset": true, + "arg_type": "NUMBER", + "value_type": "CHAR", + "signed": true, + "is_integer": true, + "step": 0, + "min": 0, + "max": 255, + "defaults": { + "value": 0 + } + } + ] + }, + { + "name": "Occluded Point Light", + "cmd_type": "Geo", + "str_cmd": "GEO_SCENE_LIGHT", + "skip_eval": false, + "children_requirements": "ANY", + "group_children": false, + "dl_option": "NONE", + "is_animated": false, + "args": [ + { + "name": "Type", + "show_as_preset": false, + "arg_type": "PARAMETER", + "value_type": "CHAR", + "signed": true, + "defaults": { + "parameter": "3" + } + }, + { + "name": "RGB", + "show_as_preset": true, + "arg_type": "COLOR", + "eval_expression": "(round(y) * 255 for y in x[:3])", + "value_type": "CHAR", + "signed": true, + "round_to_sm64": false, + "defaults": { + "color": [ + 1.0, + 1.0, + 1.0, + 1.0 + ] + } + }, + { + "name": "Quadratic falloff", + "show_as_preset": true, + "arg_type": "NUMBER", + "value_type": "CHAR", + "signed": true, + "is_integer": true, + "step": 0, + "min": 0, + "max": 255, + "defaults": { + "value": 0 + } + }, + { + "name": "Linear falloff", + "show_as_preset": true, + "arg_type": "NUMBER", + "value_type": "CHAR", + "signed": true, + "is_integer": true, + "step": 0, + "min": 0, + "max": 255, + "defaults": { + "value": 0 + } + }, + { + "name": "Constant falloff", + "show_as_preset": true, + "arg_type": "NUMBER", + "value_type": "CHAR", + "signed": true, + "is_integer": true, + "step": 0, + "min": 0, + "max": 255, + "defaults": { + "value": 0 + } + } + ] + }, + { + "name": "Directional Light", + "cmd_type": "Geo", + "str_cmd": "GEO_SCENE_LIGHT", + "skip_eval": false, + "children_requirements": "ANY", + "group_children": false, + "dl_option": "NONE", + "is_animated": false, + "args": [ + { + "name": "Type", + "show_as_preset": false, + "arg_type": "PARAMETER", + "value_type": "CHAR", + "signed": true, + "defaults": { + "parameter": "1" + } + }, + { + "name": "RGB", + "show_as_preset": true, + "arg_type": "COLOR", + "eval_expression": "(round(y) * 255 for y in x[:3])", + "value_type": "CHAR", + "signed": true, + "round_to_sm64": false, + "defaults": { + "color": [ + 1.0, + 1.0, + 1.0, + 1.0 + ] + } + }, + { + "name": "Direction", + "show_as_preset": true, + "arg_type": "ROTATION", + "inherit": true, + "eval_expression": "(cast_integer(round(y / 360.0 * 0x80), 8, False) for y in x)", + "value_type": "CHAR", + "signed": true, + "round_to_sm64": false, + "order": "XYZ", + "relative": true, + "apply_scale": false, + "rot_type": "EULER", + "defaults": { + "euler": [ + 0.0, + -0.0, + 0.0 + ] + } + } + ] + }, + { + "name": "Ambient Light", + "cmd_type": "Geo", + "str_cmd": "GEO_SCENE_LIGHT", + "skip_eval": false, + "children_requirements": "ANY", + "group_children": false, + "dl_option": "NONE", + "is_animated": false, + "args": [ + { + "name": "Type", + "show_as_preset": false, + "arg_type": "PARAMETER", + "value_type": "CHAR", + "signed": true, + "defaults": { + "parameter": "0" + } + }, + { + "name": "RGB", + "show_as_preset": true, + "arg_type": "COLOR", + "eval_expression": "(round(y) * 255 for y in x[:3])", + "value_type": "CHAR", + "signed": false, + "round_to_sm64": false, + "defaults": { + "color": [ + 1.0, + 1.0, + 1.0, + 1.0 + ] + } + }, + { + "name": "", + "show_as_preset": false, + "arg_type": "NUMBER", + "value_type": "CHAR", + "signed": false, + "is_integer": true, + "step": 0, + "min": 0, + "max": 255, + "defaults": { + "value": 0 + } + }, + { + "name": "", + "show_as_preset": false, + "arg_type": "NUMBER", + "value_type": "CHAR", + "signed": false, + "is_integer": true, + "step": 0, + "min": 0, + "max": 255, + "defaults": { + "value": 0 + } + }, + { + "name": "", + "show_as_preset": false, + "arg_type": "NUMBER", + "value_type": "CHAR", + "signed": false, + "is_integer": true, + "step": 0, + "min": 0, + "max": 255, + "defaults": { + "value": 0 + } + } + ] + } + ] + } +} \ No newline at end of file diff --git a/sm64/custom_commands/example_lighting_engine_empty.png b/sm64/custom_commands/example_lighting_engine_empty.png new file mode 100644 index 0000000..7817e13 Binary files /dev/null and b/sm64/custom_commands/example_lighting_engine_empty.png differ diff --git a/sm64/custom_commands/example_lighting_engine_presets.png b/sm64/custom_commands/example_lighting_engine_presets.png new file mode 100644 index 0000000..784398b Binary files /dev/null and b/sm64/custom_commands/example_lighting_engine_presets.png differ diff --git a/sm64/custom_commands/layer.png b/sm64/custom_commands/layer.png new file mode 100644 index 0000000..5dc8778 Binary files /dev/null and b/sm64/custom_commands/layer.png differ diff --git a/sm64/custom_commands/matrix.png b/sm64/custom_commands/matrix.png new file mode 100644 index 0000000..bef64a6 Binary files /dev/null and b/sm64/custom_commands/matrix.png differ diff --git a/sm64/custom_commands/number.png b/sm64/custom_commands/number.png new file mode 100644 index 0000000..ba20a4f Binary files /dev/null and b/sm64/custom_commands/number.png differ diff --git a/sm64/custom_commands/parameter.png b/sm64/custom_commands/parameter.png new file mode 100644 index 0000000..4a03360 Binary files /dev/null and b/sm64/custom_commands/parameter.png differ diff --git a/sm64/custom_commands/rotation.png b/sm64/custom_commands/rotation.png new file mode 100644 index 0000000..02e74ec Binary files /dev/null and b/sm64/custom_commands/rotation.png differ diff --git a/sm64/custom_commands/scale.png b/sm64/custom_commands/scale.png new file mode 100644 index 0000000..5c5ec04 Binary files /dev/null and b/sm64/custom_commands/scale.png differ diff --git a/sm64/custom_commands/translation.png b/sm64/custom_commands/translation.png new file mode 100644 index 0000000..35b46cb Binary files /dev/null and b/sm64/custom_commands/translation.png differ diff --git a/sm64/index.rst b/sm64/index.rst index d8dd805..0d4d12f 100644 --- a/sm64/index.rst +++ b/sm64/index.rst @@ -4,9 +4,11 @@ Super Mario 64 Documentation specific to the SM64 side of Fast64. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 animations/index + custom_commands/custom_commands + .. toctree:: :maxdepth: 1