diff --git a/sm64/animations/action_inspector.png b/sm64/animations/action_inspector.png new file mode 100644 index 0000000..3a038c4 Binary files /dev/null and b/sm64/animations/action_inspector.png differ diff --git a/sm64/animations/add_action.png b/sm64/animations/add_action.png new file mode 100644 index 0000000..bdcb389 Binary files /dev/null and b/sm64/animations/add_action.png differ diff --git a/sm64/animations/binary_exporter.png b/sm64/animations/binary_exporter.png new file mode 100644 index 0000000..c346569 Binary files /dev/null and b/sm64/animations/binary_exporter.png differ diff --git a/sm64/animations/c_exporter.png b/sm64/animations/c_exporter.png new file mode 100644 index 0000000..97e97cc Binary files /dev/null and b/sm64/animations/c_exporter.png differ diff --git a/sm64/animations/engine.rst b/sm64/animations/engine.rst new file mode 100644 index 0000000..dac7ac6 --- /dev/null +++ b/sm64/animations/engine.rst @@ -0,0 +1,164 @@ +How Animations Work +=================== + +Animation Variant (Header) Format +--------------------------------- +**Flags** (``s16 flags`` ``[0-2]``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + - **Bit 0** *No Loop* (``ANIM_FLAG_NOLOOP``): + The animation will not repeat from the loop start after reaching the loop end frame. + - **Bit 1** *Loop Backwards* (``ANIM_FLAG_FORWARD`` or ``ANIM_FLAG_BACKWARD`` in refresh 16): + The animation will loop (or stop if looping is disabled) after reaching the loop start frame. + Tipically used with animations which use acceleration to play an animation backwards. + - **Bit 2** *No Acceleration* (``ANIM_FLAG_2`` or ``ANIM_FLAG_NO_ACCEL`` in HackerSM64): + Acceleration will not be used when calculating which animation frame is next. + - **Bit 3** *Only Translate Horizontally* (``ANIM_FLAG_HOR_TRANS``): + Only the animation horizontal translation will be applied during rendering + (takes priority over no translation, shadows included) the vertical translation will still be included. + - **Bit 4** *Only Translate Vertically* (``ANIM_FLAG_VERT_TRANS``): + Only the animation vertical translation will be applied during rendering + (takes priority over no translation and only horizontal, shadows included) + the horizontal translation will still be included. + - **Bit 5** *No Shadow Translation* (``ANIM_FLAG_5`` or ``ANIM_FLAG_DISABLED`` in HackerSM64): + Shadows do not rely on the matrix stack, they are translated using the animation’s translation directly. + This flag disables that behavior. + - **Bit 6** *No Translation* (``ANIM_FLAG_6`` or ``ANIM_FLAG_NO_TRANS`` in HackerSM64): + The animation translation will not be used during rendering (shadows included), + the translation will still be included. + - **Bit 7** *Unused* (``ANIM_FLAG_7`` or ``ANIM_FLAG_UNUSED`` in HackerSM64): + Has no behavior and is not used on any animation. Only exists as a decomp enum. + +**Translation Divisor** (``s16 animYTransDivisor`` ``[2-4]``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If set to 0, the translation multiplier will be 1. +Otherwise, the translation multiplier is determined by dividing the object's +translation dividend (animYTrans) by this divisor. + +**Start Frame** (``s16 startFrame`` ``[4-6]``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The starting frame of the animation, not the same as loop start. + +**Loop Start Frame** (``s16 loopStart`` ``[6-8]``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +If *Backwards* is not set, this will be the starting frame after each loop, +otherwise this will be treated as the loop end frame. + +**(Loop) End Frame** (``s16 loopEnd`` ``[8-10]``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Both the end loop frame and the actual end frame. +If *Backwards* is not set, this will be the ending frame of the animation, +otherwise this will be treated as the loop start frame. + +**Bone Count** (``s16 boneCount`` ``[10-12]``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The number of bones in the animation. +Usually equal to the number of bones rendering at the same time in the model with some exceptions (Amp, Door, etc). + +Derived from the ``size of the indice table`` / 2 (Pair size) / 3 (Axis count) - 1 (Translation) + +**Values Table** (``const s16 *values`` ``[12-16]``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Pointer to array of 16-bit values of arbitrary length. See `Animation Data Format`_ + +**Indice Table** (``const s16 *index`` ``[16-20]``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Pointer to array of 16-bit indices of arbitrary length. See `Animation Data Format`_ + +**Length** (``u32 length`` ``[20-24]`` ``Unused``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +DMA exclusive property (0 in all other actors), see `DMA Table Animations (Mario)`_ + +---------------------------- + +Animation Data Format +--------------------- +Animation data is stored using two tables, the **indice table** (unsigned 16-bit) and the **values table** (signed 16-bit). + +The root bone has data for translation and rotation, all other bones only have data for rotation. +Translation is in XYZ order in normal SM64 units (just casted to s16). +Rotations are represented as euler angles in XYZ order, each angle is in degrees normalized to 16-bit: + + ``0° = 0``, ``90° = 16384 (0x4000)``, ``180° = -32768 (0x8000)``, ``270° = -16384 (0xC000)`` + +The engine iterates through the indice table to find the value for each axis in the current frame. +Each pair of values represents an axis: + + #. Frame Count (The number of frames for the axis) + #. Value Table Offset (Offset into the values table in the header) + +The first 3 axis are the translation, all following axis are rotations. + +Example: +~~~~~~~~ +In this example, the animation will loop from frame 0 to frame 4. +There will be no translation (all values will be 0) and the angles will all rotate from 0° to 270°. + +.. code-block:: c + + static const s16 values_table[4] = { + 0x0000, 0x4000, 0x8000, 0xC000 + }; + + static const s16 indice_table[4] = { + /*translation - x*/ 1, 0, // offset 0, 1 frame, value 0 + /*translation - y*/ 1, 0, // offset 0, 1 frame, value 0 + /*translation - z*/ 1, 0, // offset 0, 1 frame, value 0 + /*rotation - x*/ 4, 0, // offset 0, 4 frames, values [0, 16384, -32768, -16384] + /*rotation - y*/ 4, 0, // offset 0, 4 frames, values [0, 16384, -32768, -16384] + /*rotation - z*/ 4, 0 // offset 0, 4 frames, values [0, 16384, -32768, -16384] + }; + + static const struct Animation header = { + .flags = 0, // No flags, will loop + .animYTransDivisor = 0, + .startFrame = 0, + .loopStart = 0, + .loopEnd = 4, + .boneCount = ANIMINDEX_NUMPARTS(indice_table), + .values = values_table, + .index = indice_table, + .length = 0 + }; + +---------------------------- + +Tables +------ +Animation tables are simple arrays of header pointers ``const struct Animation *const anim_table[]``, +they get set using the ``LOAD_ANIMATIONS(field (Always oAnims), anim_table)`` behavior script command. +Mario loads his animations dynamically, see `DMA Table Animations (Mario)`_ + +Example: +~~~~~~~~ +.. code-block:: c + + static const struct Animation *const anim_table[] = { + &anim_00, + &anim_01, + NULL + }; + +``cur_obj_init_animation(index)`` and its variations or the behavior script command ``ANIMATE(index)`` +can be used to play an animation in the table of the current object. + +---------------------------- + +DMA Table Animations (Mario) +---------------------------- + +Mario animations use a DMA table (like the demos' input), this stores normal animation data for the most part, +only differing in 2 things: + +- The value and indice table pointers are offsets within each DMA entry +- Length is set to the size in bytes of the entry + (which goes unused since that's part of the DMA entrie offset-size pair struct) + +To play an animation, ``set_mario_animation()`` or ``set_mario_anim_with_accel()`` is used. + +| One entry could load two headers (variants) if they are using the same indice and values table. +| For example, anim_00 (Slow Ledge Climb Up) and anim_01 (Fall Over Backwards) use the same indice and values table, so the data would be structured like this: +| ``anim_00 header, anim_01 header, values and indice tables`` +| To load anim_00, the engine has to read anim_01's header as well, since it's in between anim_00 and the data. +| But if you load anim_01, it will not load anim_00's header. + +For more information, see :doc:`DMA Tables <../dma_table>`. diff --git a/sm64/animations/exporting.rst b/sm64/animations/exporting.rst new file mode 100644 index 0000000..bb17acc --- /dev/null +++ b/sm64/animations/exporting.rst @@ -0,0 +1,238 @@ +Creating Animations +=================== + +Animation Object +---------------- +To export an animation, you will need a rig with animation bones (*"Animated Part (0x13)"* or *"Custom Animated"*) +or a mesh with the *"Geolayout Command"* set to *"Animated Part (0x13)"* + +In armatures, the bones will follow the same order as their geolayout counterpart. +Switch bones are ignored so make sure your default option is the one with all the bones! + +Adding An Action +---------------- +To add an action to your object, select it and use the *"Add Basic Action"* button +in the *"Action Inspector"* sub-panel of *"SM64 Animation Inspector"*. +This will automatically stash your action in the NLA tracks of the selected object. + +.. image:: add_action.png + :align: center + :alt: SM64 Animation Inspector with the Action Inspector sub-panel opened + +----------------------------------------------------------------------------- + +Animation Object Properties +--------------------------- + +The animation object's properties are shown in object properties in the *"SM64 Animation Inspector"* panel. + +.. image:: obj_inspector.png + :align: center + :alt: SM64 Animation Inspector under object properties panel + +| You can find the elements of the table in the *"Table"* sub-panel. See `Table Element`_ +| And you can inspect action properties in the *"Action Inspector"* sub-panel (Also found under the scene panel equivelent). See `Action Properties`_ + + +**"Is DMA Export"**: + +Is this animation object's table and actions exported in DMA table format (Like Mario). + +**"Update Table"**: (Only available with *"Is DMA Export"* disabled in the animation object and *"Export Single Action"*) + +In C exports, creates and updates the table along with includes. +In Binary, updates the table pointer at the index of the exported variants. + +**"Table Name"**: (C. Only available outside DMA) + +The name of the exported table. + +**"Generate Enums"**: (C. Only available outside DMA) + +| Enable to generate the enums for the variants, + they will be named after the variant name and can be used within actor scripts and functions. + Example: ``cur_obj_init_animation(MARIO_ANIM_ACTION);`` +| Custom names for the enum list and end enum are not supported. + +| With *"Designated Initialization"*, tables will use the enum as the index directly using designated initialization. + For example ``[MARIO_ANIM_ACTION] = mario_anim_action;``. +| This feature is not supported in older C compilers like IDO, + without it enums will still be generated but can desync by user mistakes. + +**"Export All Separately"**: (C. Only available outside DMA. Only applicable with *"Export Single Action"* disabled) + +Export each animation (data and variants) in a Separete file. Reduces compression. + +**"Override Table and Data Files"**: (C. Only available outside DMA. Only applicable with *"Export Single Action"* disabled. Forced if *"Export All Separately"* is disabled) + +Override the table and data files that are exported instead of appending new includes and table elements. + +**"Add NULL Delimiter"**: (Only available outside DMA. Only applicable in binary with *"Export Single Action"* disabled) + +Add a ``NULL (0x00)`` delimiter to the end of the table. + +**"Beginning Animation"**: (C and binary. Only available outside DMA, only available with *"Export Behavior"* enabled in C or *"Update Behavior"* in Binary) + +The animation used in the ANIMATE command of the behavior script. + +**"Table Start/End Address"**: (Binary) + +Where the table will export to, outside DMA it will be used for updating table pointers if *"Update Table"* is enabled. + +**"Update Behavior"**: (Binary. Only available outside DMA) + +| Update the behavior script ``ANIMATE`` command with *"Beginning Animation"* and the ``LOAD_ANIMATIONS`` command with the table address. +| Will not error if the ``ANIMATE`` command is not found, check the console if you want to know if it was found. +| The behavior script can be found under this toggle as *"Behavior"*, + select ``Custom`` to set a specific address, otherwise use the search button. + +**"Write Data Separately"**: (Binary. Only available outside DMA) + +Write the animation data to a Separete address range (*"Data Start/End Address"*) instead of after the animation table. + +**"File Name"**: (Insertable Binary) + +The file name for the exported animation table. + +------------------------------------------------------------------------------------------------------------------------- + +Table Element +------------- +A table element points to an animation and one of its variants. + +.. image:: table_elements.png + :align: center + :alt: Two table elements under the "Table" sub-panel, one a normal table element and another a reference. + +**"Action"**: + +The animation that owns the variant. + +**"Variant"**: + +The number of the variant, 0 is the main variant. + +**"Enum"**: (C. Only available outside DMA with *"Generate Enums"* enabled in the animation object) + +The enum that will represent the animation index. + +**"Reference"**: (Only available outside DMA) + +C name or address of an animation variant (header) + +------------------------------------------------------------- + +Action Properties +----------------- +.. image:: action_inspector.png + :align: center + :alt: SM64 Action Inspector sub-panel + +**"File Name"**: (C and Insertable Binary. Only applicable with *"Export All Separately"* enabled in the animation object or with *"Export Single Action"*) + +The file name of the exported animation. + +**"Max Frame"**: + +The amount of frames to export. Separete from the loop points of the variants. + +**"Reference Tables"**: (Only applicable outside DMA) + +Pass in references to existing animation data. + +**"Start/End Address"**: (Binary. Only available with *"Export Single Action"*) + +The start and end address where the animation will be exported to. + +-------------------------------------------------------------------- + +Header Variants +--------------- +Each variant represents a way to play back the animation data. +You can add the variant to the animation object's table by pressing *"Add To Table"*. +Use the *"Preview Animation"* button to preview the animation, sets FPS to 30 and emulates loop points. + +**"Table Index"**: (Only available for *"Export All Separately"* for DMA or Binary if *"Update Table"* is on) + +| The index in the animation table. +| In binary (non DMA) is used to update the pointer at that index in the table. +| In binary (DMA) is used to know what header to substitute on re-export. + +**"Enum"**: (C. Only available outside DMA with *"Generate Enums"* enabled in the animation object) +The enum that will represent the animation index. + +**"Name"**: (C. Only available outside DMA) + +The name of the animation variant that will be exported. + +**"Translation Divisor"**: + +If set to 0, the translation multiplier will be 1. +Otherwise, the translation multiplier is determined by dividing the object's +translation dividend (animYTrans) by this divisor. + +**"Manual Loop Points"**: + +When enabled, you can manually set the loop points. + +- *"Start"*: The starting frame of the animation, not the same as loop start. +- *"Loop Start"*: If *Backwards* is not set, this will be the starting frame after each loop, + otherwise this will be treated as the loop end frame. +- *"End"*: Both the end loop frame and the actual end frame. + If *Backwards* is not set, this will be the ending frame of the animation, + otherwise this will be treated as the loop start frame. + +**Flags**: + +Custom flags will be evaludated for binary and DMA, you can still use known flags in C. + +- *"Loop"*: The animation will repeat from the loop start after reaching the loop end frame. +- *Loop Backwards*: The animation will loop (or stop if looping is disabled) after reaching the loop start frame. Tipically used with animations which use acceleration to play an animation backwards. +- *Acceleration*: Acceleration will be used when calculating which animation frame is next. +- *Translation*: The animation translation will be used during rendering (shadows included), when disabled the translation will still be exported. +- *Only Horizontal*: Only the animation horizontal translation will be applied during rendering (takes priority over translation being disabled, shadows included) the vertical translation will still be exported. +- *Only Vertical*: Only the animation vertical translation will be applied during rendering (takes priority over translation being disabled and only horizontal, shadows included) the horizontal translation will still be exported. +- *Shadow*: Apply translation to the object's shadow. + +============================================= + +Exporting Animations +==================== + +**"Quick Data Read"**: +Read fcurves directly, should work with the majority of rigs, +if your rig uses features such as bone contraints you will need to disable this. + +- `Exporting C`_ +- `Exporting Binary`_ +- `Exporting Insertable Binary`_ + +------------------------------ + +Exporting C +----------- +| Enable *"Export Animations"* in the *"SM64 Combined Exporter"* scene panel. +| Enable *"Export Single Action"* to export the object's selected action, this is the old workflow from the old exporter. +| DMA exports will be relative to the custom path with the *"Custom"* header type. + +.. image:: c_exporter.png + :align: center + :alt: SM64 Combined Exporter with the *"Export Animations"* enabled + +Exporting Binary +---------------- +| Set *"Level"* to where the animations will be loaded. +| *"Export Individual Animation"* is the equivelent of *"Export Single Action"* toggle for the C exporter. + +.. image:: binary_exporter.png + :align: center + :alt: text + +Exporting Insertable Binary +---------------------------- +| Set *"Directory"* to where you want your files to be exported to. +| *"Export Individual Animation"* is the equivelent of *"Export Single Action"* toggle for the C exporter. + +.. image:: insertable_exporter.png + :align: center + :alt: text diff --git a/sm64/animations/importer.png b/sm64/animations/importer.png new file mode 100644 index 0000000..ee943de Binary files /dev/null and b/sm64/animations/importer.png differ diff --git a/sm64/animations/importing.rst b/sm64/animations/importing.rst new file mode 100644 index 0000000..d7e0506 --- /dev/null +++ b/sm64/animations/importing.rst @@ -0,0 +1,97 @@ +Importing Existing Animations +============================= + +To import animations, you will need a rig. +See the `Importing/Exporting SM64 Geolayouts `_ +documentation or use the `Example Mario Model `_ + +Enable *"Show Importing Menus"* in the *"SM64 General Settings"* panel. + +.. image:: ../showing_importing_menus.png + :align: center + :alt: SM64 Animation Inspector with the importing sub-panel opened + +After that, the sub-panel *"Importing"* under *"SM64 Animation Inspector"* will be visible. + +.. image:: importer.png + :align: center + :alt: SM64 Animation Inspector with the importing sub-panel opened + +Set *"Type"* based on your import goal and follow the relevant instructions: + - `C <#importing-existing-animations-c>`_ + - `Binary <#importing-existing-animations-binary>`_ + - `Insertable Binary <#importing-existing-animations-insertable-binary>`_ + +Importing Existing Animations (C) +--------------------------------- +Presets: +~~~~~~~~ +- Use the search button next to the *"Preset"* dropdown. +- Enable *"Read Entire Table"* to import all animations (default), or disable it to select individual animations (use custom for a specific index). + +Custom Presets: +~~~~~~~~~~~~~~~ +- Select *"Custom"*, choose a folder/file, or set the decomp path in the importer or general settings. +- Enable *"Use Custom Name"* for original names. + +See `General Import Settings`_ for more. + +Importing Existing Animations (Binary) +-------------------------------------- + +Setting Up the ROM +~~~~~~~~~~~~~~~~~~ +.. include:: ../enable_importing_binary.rst + +Presets: +~~~~~~~~ +- Use the search button next to the *"Preset"* dropdown. +- Enable *"Read Entire Table"* to import all animations (default), or disable it to select individual animations (use custom for a specific index). + +Custom Presets: +~~~~~~~~~~~~~~~ +- Select *"Custom"* in the *"Preset"* dropdown. +- Configure the following options based on import type: + - *"DMA"*: Import from a DMA table (Mario), you will need to set the *"DMA Table Address"* to the address in ROM. + - *"Table"*: + Import from a table, you will need to enable/disable *"Is Segmented Address"* and set the address of the table, + set *"Level"* to a level where the table is loaded. + + To import the entire table, enable *"Read Entire Table"* (on by default), otherwise choose an index. + + Enable *"Check NULL Delimiter"* if the table's last element is a ``NULL (0x00)``, + otherwise set *"Size"* to the amount of elements if you have *"Read Entire Table"* enabled. + - *"Animation"*: Import a single animation, you will need to enable/disable *"Is Segmented Address"*, set the address of the animation header + and set *"Level"* to a level where the animation is loaded. + +- Enable *"Ignore Bone Count"* to ignore the bone count of the target armature, + this is necesary for when headers have a different bone count than the target armature. + +Importing Existing Animations (Insertable Binary) +------------------------------------------------- +There are no presets for this type. + +Enable *"Ignore Bone Count"* to ignore the bone count of the target armature, +this is necesary for when headers have a different bone count than the target armature. + +Table Import Settings +~~~~~~~~~~~~~~~~~~~~~~ +When importing an insertable binary file of table type (4), the settings under *"Table Imports"* are used. + +- To import the entire table, enable *"Read Entire Table"* (on by default), otherwise choose an index. +- Enable *"Check NULL Delimiter"* if the table's last element is a ``NULL (0x00)``, otherwise set *"Size"* to the amount of elements if you have *"Read Entire Table"* enabled. + +General Import Settings +~~~~~~~~~~~~~~~~~~~~~~~ +| The built-in animation f-curve decimate operator can be used to automatically clean up animations on import. + Enable *"Run Decimate (Allowed Change)"* (on by default) to use it. +| This is recommended for the ease of editing animations. The default error margin should keep the animation visually intact. +| **Be warned** this can be a bit slow. + +| For armatures without actions, enable *"Force Quaternions"*, + this sets all the animated bones in the armature to the quaternion rotation mode, which prevents gimbal lock. +| Alternatively, enable *"Continuity Filter"* (on by default) to at least fix any existing gimbal lock in the animations. + +Enable *"Clear Table On Import"* (on by default) to clear the table elements of the armature on import. + +Finally, select your armature and click *"Import Animation(s)"*. diff --git a/sm64/animations/index.rst b/sm64/animations/index.rst new file mode 100644 index 0000000..02f8da9 --- /dev/null +++ b/sm64/animations/index.rst @@ -0,0 +1,9 @@ +Animations +========== + +.. toctree:: + :maxdepth: 1 + + v24 + v25 + engine diff --git a/sm64/animations/insertable_exporter.png b/sm64/animations/insertable_exporter.png new file mode 100644 index 0000000..b3a6b76 Binary files /dev/null and b/sm64/animations/insertable_exporter.png differ diff --git a/sm64/animations/obj_inspector.png b/sm64/animations/obj_inspector.png new file mode 100644 index 0000000..a38d17e Binary files /dev/null and b/sm64/animations/obj_inspector.png differ diff --git a/sm64/animations/table_elements.png b/sm64/animations/table_elements.png new file mode 100644 index 0000000..c961da0 Binary files /dev/null and b/sm64/animations/table_elements.png differ diff --git a/sm64/animations/v24.rst b/sm64/animations/v24.rst new file mode 100644 index 0000000..d5ebf75 --- /dev/null +++ b/sm64/animations/v24.rst @@ -0,0 +1,45 @@ +2.4.0 +===== + +Importing/Exporting Binary SM64 Animations (Not Mario) +------------------------------------------------------ + + +* Note: SM64 animations only allow for rotations, and translation only on the root bone. + +* Download Quad64, open the desired level, and go to Misc -> Script Dumps. + +* Go to the objects header, find the object you want, and view the Behaviour Script tab. +* For most models with animation, you can will see a 27 command, and optionally a 28 command. + +For importing: +~~~~~~~~~~~~~~ +* The last 4 bytes of the 27 command will be the animation list pointer. +* Make sure 'Is DMA Animation' is unchecked, 'Is Anim List' is checked, and 'Is Segmented Pointer' is checked. +* Set the animation importer start address as those 4 bytes. +* If a 28 command exists, then the second byte will be the anim list index. +* Otherwise, the anim list index is usually 0. + +For exporting: +~~~~~~~~~~~~~~ +* Make sure 'Set Anim List Entry' is checked. +* Copy the addresses of the 27 command, which is the first number before the slash on that line. +* Optionally do the same for the 28 command, which may not exist. +* If a 28 command exists, then the second byte will be the anim list index. +* Otherwise, the anim list index is usually 0. + +Select an armature for the animation, and press 'Import/Export animation'. + +Importing/Exporting Binary Mario Animations +------------------------------------------- + +Mario animations use a DMA table, which contains 8 byte entries of (offset from table start, animation size). +Documentation about this table is +`here `_ + +Basically, Mario's DMA table starts at 0x4EC000. There is an 8 byte header, and then the animation entries afterward. Thus the 'climb up ledge' DMA entry is at 0x4EC008. The first 4 bytes at that address indicate the offset from 0x4EC000 at which the actual animation exists. Thus the 'climb up ledge' animation entry address is at 0x4EC690. Using this table you can find animations you want to overwrite. Make sure the 'Is DMA Animation' option is checked and 'Is Segmented Pointer' is unchecked when importing/exporting. Check "Overwrite DMA Entry", set the start address to 4EC000 (for Mario), and set the entry address to the DMA entry obtained previously. + +Animating Existing Geolayouts +----------------------------- + +Often times it is hard to rig an existing SM64 geolayout, as there are many intermediate non-deform bones and bones don't point to their children. To make this easier you can use the 'Create Animatable Metarig' operator in the SM64 Armature Tools header. This will generate a metarig which can be used with IK. The metarig bones will be placed on armature layers 3 and 4. diff --git a/sm64/animations/v25.rst b/sm64/animations/v25.rst new file mode 100644 index 0000000..34095e2 --- /dev/null +++ b/sm64/animations/v25.rst @@ -0,0 +1,8 @@ +2.5.0+ +====== + +.. toctree:: + :maxdepth: 2 + + importing + exporting diff --git a/sm64/dma_table.rst b/sm64/dma_table.rst new file mode 100644 index 0000000..0787f4b --- /dev/null +++ b/sm64/dma_table.rst @@ -0,0 +1,24 @@ +DMA Tables +========== + +DMA Tables are used for data that needs to be loaded dynamically, such as animations and demo inputs. +They are uncompressed, so their data is DMA'd into memory directly, hence the name. + +Format +------ + +**Number of Entries** (``u32 numEntries`` ``[0-4]``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +How many entries are in the table. + +**Source Address** (``const void *addrPlaceholder`` / ``u8 *srcAddr`` ``[4-8]``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Set to NULL in the ROM, exists for knowing the ROM address after setting up the handler in ``setup_dma_table_list()``. + +**Entries** (``struct OffsetSizePair[numEntries]`` ``[8-(numEntries*8 + 8)]``): +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +**Offset Size Pair** (``struct OffsetSizePair``): + - **Offset** (``u32 offset`` ``[0-4]``): + Offset from the start of the table. + - **Size** (``u32 size`` ``[4-8]``): + Size in bytes of the entry. \ No newline at end of file diff --git a/sm64/enable_importing_binary.rst b/sm64/enable_importing_binary.rst new file mode 100644 index 0000000..693c218 --- /dev/null +++ b/sm64/enable_importing_binary.rst @@ -0,0 +1,6 @@ +| You will need an extended ROM (unless you only want to import Mario's animations, which are uncompressed). +| For this, you can use `ROM Manager `_ + or alternatively `sm64Extend `_. + +Enable *"Show Importing Menus"* in the panel *"SM64 General Settings"*. +Then set the *"Import ROM"* to your extended ROM's path. \ No newline at end of file diff --git a/sm64/index.rst b/sm64/index.rst index 185410d..d8dd805 100644 --- a/sm64/index.rst +++ b/sm64/index.rst @@ -2,3 +2,12 @@ Super Mario 64 ============== Documentation specific to the SM64 side of Fast64. + +.. toctree:: + :maxdepth: 2 + + animations/index +.. toctree:: + :maxdepth: 1 + + dma_table \ No newline at end of file diff --git a/sm64/showing_importing_menus.png b/sm64/showing_importing_menus.png new file mode 100644 index 0000000..2278b07 Binary files /dev/null and b/sm64/showing_importing_menus.png differ