pantin

This page is docs/godot.md of the repository, as it is on main.

Pantin in Godot

runtimes/godot is the Godot runtime of pantin: a GDExtension written in Rust with godot-rust 0.5.5, over the same pantin-runtime and pantin-core as the application. It adds one node, PantinCharacter, that plays the character of a pantin character in a scene, from the bundle pantin build writes or from the project folder: its graph of states, or its animations on tracks, crossfaded, its springs swinging as the node moves, its constraints, its meshes and clips, its boxes, and its events as signals. A game shows what the editor showed, computed by the same code.

The robot of the examples played by a PantinCharacter in Godot

What it lacks is said at the end.

In the browser

The example can be exported for the web, to be played in a browser.

tools/godot_web.sh <out> builds it: the library for the web by emscripten 4.0.20, the version Godot 4.7.2 was built with, and a Rust nightly of a given day that builds the standard library for the web (--features web, the experimental-wasm of godot-rust); then Godot exports the example with its template web_dlink_nothreads_release, which tools/godot_template.py takes out of the release alone. With no threads, the page needs no cross-origin isolation from its server. Panics abort there: the engine of the web has no exceptions of WebAssembly to unwind them with.

Trying the example

The example is a Godot project in runtimes/godot/example: the robot of the examples, walking with the arrows and waving with Space. It needs Godot 4.6 or later.

tools/godot_example.sh            # builds the library, copies it and the robot into the example
godot -e --path runtimes/godot/example

tools/godot_example.sh --release builds the library optimised, as a game would ship it. The script copies the projects rather than linking them: Godot packs what is inside the folder of the game.

In a game of your own

  1. Build the library (cargo build -p pantin-godot --release) and put it in the game, in bin/: libpantin_godot.so on Linux, pantin_godot.dll on Windows, libpantin_godot.dylib on macOS.
  2. Copy runtimes/godot/example/pantin.gdextension beside it, at the root of the game.
  3. Write the bundle of each character, pantin build name.pantin --out game/characters/name.pantinpack, and choose it as the Bundle of a PantinCharacter in a scene. One file holds the skeleton, the animations, the boxes, the graph and the atlas.
  4. Or copy the project folder (name.pantin, with its pantin.toml, its rig.json, its hit.json and flow.json when it has them, and its images) into the game, and choose it as the Project: Godot imports its PNG and SVG images as textures.
  5. When exporting, add *.pantinpack (or *.toml, *.json for a folder) to Filters to export non-resource files of the preset: Godot packs only its own resources otherwise, and the character would not be found.

The node is a @tool: it plays in the editor as in the game.

The node

PantinCharacter is a Node2D. The skeleton has y up and the node y down: the runtime turns one into the other, and a unit of the project is a pixel of the node.

Property
bundle The bundle, res://…/name.pantinpack, read first. Set again, it is read again.
project The project folder, res://…/name.pantin, read when there is no bundle. Set again, the project is read again.
animation The animation played on track 0 once the character is read. When empty, a character whose project has a graph of states follows it from its entry.
looping Whether that animation starts again at its end. On at first.
speed How fast the time of the character passes, 1 as made.
Method
fire(trigger) -> bool Fires a trigger of the graph: jump, attack. False when it has none of that name.
set_number(name, value) -> bool, set_switch(name, on) -> bool Sets a number or a switch of the graph.
set_slider(name, time) -> bool, clear_slider(name) -> bool Sets the time of a slider, in seconds, over its keys: the character takes the pose its animation has then; clear_slider gives it back to the keys.
get_state() -> String The state of the graph the character is in; empty when it follows none.
get_active_boxes() -> Array The boxes active now, each a dictionary: name, kind (hit, hurt, push) and corners, a PackedVector2Array in the space of the node.
play(animation, track, looping, fade) -> bool Plays an animation on a track from its start, going from what the track played over fade seconds; a character that followed its graph leaves it. False when the project has no such animation.
stop(track) Stops a track at once.
set_track_weight(track, weight) How much a track weighs over those under it, from 0 to 1.
set_skin(name), get_skin() The skin shown, by name (empty: none): its images first, and the bones and constraints only some skins have are there while one of them is shown. set_skin says false when there is no skin of that name.
set_track_additive(track, additive) Whether a track adds what its animation changes from the setup pose to the tracks under it, instead of putting it in their place.
get_playing(track) -> String The animation a track plays, empty when none.
get_animations() -> PackedStringArray The animations of the project.
get_bone_transform(bone) -> Transform2D Where a bone is now, in the space of the node: to hang a Godot node on a hand.
settle() Forgets the swing of the springs, after the node was put somewhere else at once.

Tracks are laid one over the other, the first at the bottom: each changes only what its animation keys, by its weight, over the tracks under it (pantin_runtime::Player). A run on track 0 and a wave on track 1 is a robot that waves as it runs. An additive track adds instead: a nod on an additive track over the run turns the head a little more than the run does, at its weight (golden values).

A character whose project has a graph of states (flow.json, the Flow workspace) follows it: the game only sets parameters and fires triggers, and the graph plays the animations, crossfaded, as the graph format says.

The signal event(name, int, float, text, track, animation) is told for each event of an animation as its time is passed: a step for a sound, a landing for dust. An animation that a track is leaving tells its events during the first half of the crossfade. state_entered(state) is told when the character enters a state of its graph, and box_edge(name, started) when a range of a box that asks for its events starts or ends: the moment a blow can land. An event that has a sound tells event_sound(name, file, volume, balance, track, animation) as well: the file is relative to the folder of the project, the volume from 0 to 1, the balance from -1 (left) to 1 (right), for an AudioStreamPlayer of the game to play.

The springs feel the node move: carried away, what hangs stays behind for a moment by its skeleton inertia, and the gravity of the skeleton pulls down the screen whatever the node's turn.

@onready var robot: PantinCharacter = $Robot

func _ready() -> void:
    robot.event.connect(func(name, _i, _f, _t, _track, _animation): print(name))

func jump() -> void:
    robot.fire("jump")

Not yet

  • The blend modes multiply and screen are drawn as normal, and the dark colour of a slot is not drawn; additive is.
  • The library is built and tested on Linux, and for the web; Windows and macOS build it the same way, untested.
  • The first --import of a project in which Godot finds the extension aborts as it quits, its work done (Godot 4.7.2, godot-rust 0.5.5); the next one ends well.

How it is tested

cargo test -p pantin-godot reads, plays and draws the robot with no Godot (runtimes/godot/src/character.rs), then plays the example in Godot, headless (runtimes/godot/tests/godot.rs and example/tests/smoke.gd): the library loads, the robot is read, plays on two tracks, its arm moves, and its two events are heard; read from its bundle it follows its graph, idle, wave when told hello, idle again; the stickman walking gives its two boxes and tells the start of the range of its foot. Godot is PANTIN_GODOT or godot on the path; the test passes over it when Godot is missing, unless PANTIN_REQUIRE_GODOT is set, as the CI does.