z64anim

From z64 wiki
Jump to: navigation, search

z64anim
Z64anim-stalfos.png
z64anim console and viewing window
Original author(s) spinout
Written in C
Operating system Cross platform
Available in English
Type CLI tool
License Open Source
Website z64anim on bitbucket.
Applicable game(s) all (works with objects)

z64anim is a tool in development by spinout with the purpose of viewing and modifying an animated object's animation and skeleton. It uses SDL, GL, threads, libobj, xdaniel's libbadRDP and the required dependencies for these libraries - libpng and lz. In its current state, it has two windows: a viewing window, and a command-line console window. The console has many commands which control viewing and editing of animations. The window is used for display list, translation and rotation axis selection and manipulation on a more graphical level.
On August 19, 2011, spinout put z64anim on bitbucket[1], and there has been some development going on as of mid September 2011. All future binary and sources can be found here.

Usage

Before using:

  • Be at least somewhat familiar with skeletons and animations - an understanding of the binary structure is not critical but an understanding of rotations used in animations and translation of children/next limbs is reccomended
  • Make sure you have the latest version of z64anim
  • Make sure you have your object ready to use. You could do some trickery with the -o and -s CMD arguments (see below) to load an object directly from ROM, but I do not recommend doing so and I am not completely sure if the saving routine will work as expected.

Invoking z64anim

z64anim can, optionally, be passed command line arguments. The last argument is to be an object containing Animations. The arguments before that can be:

-G
Enable OpenGL ARB extensions in badrdp
-o OFF
Read data from the input file starting at offset OFF (Default: 0)
-s SIZ
Read SIZ bytes of data. (Default: OFF -> end)
-b BASE
Set base address of data to BASE (Default: 0x06000000)

Example:

z64anim.exe object_sk2.zobj

Due to the fact that z64anim expects the last argument to be the object file itself, an object file can be dragged and dropped onto the application.

Window controls

Keyboard controls

Key(s)Action
w,s,a,dMove camera
q,eChange camera speed
rReset camera
u,jIncrease/decrease animation playback speed
h,kChange to next/previous animation
(space)Pause/play animation
y,iIncrease/decrease current animation/translation value
o,lIncrease/decrease current animation index
(up arrow)Select previous limb
(down arrow)Select next limb
(right arrow)Select parent limb
(left arrow)Select child limb
xToggle x/y/z axis
vToggle drawing of rotation guides
mSwitch edit mode (display list/translation/rotation)

Mouse Controls
The mouse is used for camera rotation when the left mouse button is held and dragged, and display lists/editing axis (when visible) can be selected with a right click.

Console Commands

Basics

These commands are always available, even when an object isn't loaded.

help
Print all controls for console and viewing window.
quit
Exit z64anim
load F B A S
Load S bytes from file F at offset A as address B. If B, A, and S are ommited, it is assumed to load the entire file from base address 0x06000000 - which is what most objects use.

Viewer Control

These commands control the rendering animation in the rendering window.

pause
Pause playing the current animation. Rendering window equivalent (toggle): (space)
play
Resume playing the current animation. Rendering window equivalent (toggle): (space)
step
Step the current animation by one frame. Rendering window equivalent: 'n'
hideaxis
Hide editor axis of each joint. Rendering window equivalent (toggle): 'v'
showaxis
Show editor axis of each joint. Rendering window equivalent (toggle): 'v'
select-disable
Disable selection of displaylists or editor axis
select-enable
Enable selection of displaylists or editor axis
scale V
Set the scale of the editor axis

Animation

anim-info
List information on the current animation
anim-list
List all known animations
anim-switch N
Switch the current animation to animation N.
anim-next
Switch to the next animation. Rendering window equivalent: 'k' ('h' for previous in rendering window)
anim-rotations
List all valid rotation indicies

Skeleton

skel-info
Display skeleton information
skel-reset
Reset the entire skeleton to the state it was at when last opened or saved

Display Lists

dl-list
List all known display lists
dl-switch N
Change current limb's display list to display list N
dl-curr
Print current display list
dl-export OBJ
Export the current DL as wavefront .obj
dl-import OBJ SIZ
Import the wavefront .obj file in FILE at size SCALE. Todo: Allow user to specify what display list # or a new index.

Values

val-info
Print information on currently selected value
val-set V
Set the current value (rotation, translation and display list #s)
val-index I
Set the current rotation index (rotations only)
val-series S I
Set the series of animated rotation values starting at S degrees increasing by I degrees each frame
val-seriesr S I
Set the series of animated rotation values starting at S degrees increasing by I degrees for each frame for the first half of the frames, then decreasing by I back to S

Selection

axis A
Switch to axis A (either `x', `y' or `z'). Rendering window equivalent (toggle): 'x'
rot
Switch to editing rotation. Rendering window equivalent (toggle): 'm'
trans
Switch to editing translation. Rendering window equivalent (toggle): 'm'
dlist
Switch to editing display list. Rendering window equivalent (toggle): 'm'
child
Select the current limb's child, if possible. Rendering window equivalent: (right)
parent
Select the current limb's parent, if possible. Rendering window equivalent: (left)
next
Select the next limb, if possible. Rendering window equivalent: (up)
previous
Select the previous limb, if possible. Rendering window equivalent: (down)

Miscellaneous

save
Apply all changes made
adopt N
Set the current limb's child to limb N

Planned

I'm probably going to have to write a library which stores and describes binary data with local pointers to implement all of these commands.

dl-export-all DIR
Export all DLs as wavefront .obj
dl-scale S
Scale the current display list to scale S
val-reset
Reset the current value
add-dlist OFFSET
Add the display list at OFFSET to the list of known display lists
anim-new
Create and select a new one-frame animation with no animated values.
anim-setframes N
Make the animation an N framed animation (adding & removing frames as needed)
anim-addtrack
Add a new animated list of values
anim-rmtrack
Remove an animated list of values
anim-addstill
Add a new still value
anim-rmstill
Remove a still value
skel-new
create a new skeleton with one limb
addchild
Add a child limb
rmchild
Remove the child limb and it's children/siblings (assuming they are not used elsewhere)
popchild
Set the child limb to the child limb's sibling limb, destroy original child limb and it's children which are not used elsewhere.
addnext
Add a next limb
rmnext
Remove the next limb and it's children (assuming they are not used elsewhere)

All of these functions which modify how many members are in a hierarchy/skeleton must also fix animations.