A2: Player figure and animation

The islander is built in headless Blender (tools/models/figure.py,
`make figure`, `make art`) as twelve rigid parts with their origins at
their joints: an oilskin coat, a sou'wester, sea boots, a bedding roll
and the canvas wing-sail. Debian's Blender can't write glTF, so the
figure is jointed rather than skinned.

FigureRig hangs the parts on pivots, paints them from Palette with the
coat in the player's own oilskin, and plays FigurePoses' hand-written
key poses through one AnimationTree: idle, walk and run by speed,
crouch and creep, air, skydive, glide, swim and aboard; long, short and
carried holds; reload and use layers; fire, boathook swing, keg throw
and building as one-shots; and a flinch when health drops. The chest
takes a third of the pitch and the held item all of it.

Figures animate from replicated state only: positions, look, health,
the held item and the FLAG_ bits (reloading and using now reach
mirrored players), with actions from FX. Every boathook swing is now a
sim "swing" event, sent as a SHOT with no item, so misses are seen and
heard; the new FX kind PLACE shows pieces placed. Protocol version 4.

Tests: test_figure_rig (15), plus swing and PLACE cases in test_harvest
and test_net_fx. make check passes (604 tests); make client-check
passes. Captures: figure_states, figure_actions, figure_close
(make figure-captures), client_glide and client_landed.

Closes #42

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-13 17:35:53 -05:00
co-authored by Claude Opus 5.5
parent da0c65f3ce
commit 07738330b5
66 changed files with 6230 additions and 88 deletions
+251
View File
@@ -0,0 +1,251 @@
"""Tidewall's player figure (A2), built in headless Blender.
blender --background --factory-startup --python tools/models/figure.py
A low-poly islander in an oilskin coat and a sou'wester, with sea boots, a rolled
bedding bundle on the back and a canvas wing-sail for the glide. Writes:
assets/models/figure/<part>.obj one model per moving part, with <part>.mtl
assets/models/figure/figure.json the joints, which part hangs from which, and
where the right hand closes
Debian's Blender can't export glTF (its exporter needs numpy), and OBJ carries no
skeleton, so the figure is a set of rigid parts. Each part's origin is the joint it
turns about; the client (FigureRig) hangs them on a hierarchy of pivots from
figure.json and animates the pivots with an AnimationTree.
Conventions, in Godot's axes after export: +Y up, the figure faces +Z, its right is
-X, and it stands with its feet at the origin, 1.8 m tall to the hat's crown.
Materials are named after Palette colours, as for items; COAT and COAT_DARK are the
player's own oilskin colour and a darker shade of it, which the client fills in.
Everything is built from primitives here, with no randomness.
"""
import json
import math
import os
import sys
import bpy
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import items # noqa: E402 (the shared builders: box, tube, ball, ring, material)
OUT_DIR = os.path.join(items.ROOT, "assets", "models", "figure")
# Joints, in Godot's axes (x, y, z): +Y up, facing +Z, the figure's right toward -X.
JOINTS = {
"hips": (0.0, 0.92, 0.0),
"waist": (0.0, 1.02, 0.0),
"neck": (0.0, 1.50, 0.0),
"shoulder_r": (-0.225, 1.42, 0.0),
"shoulder_l": (0.225, 1.42, 0.0),
"elbow_r": (-0.235, 1.14, 0.0),
"elbow_l": (0.235, 1.14, 0.0),
"hip_r": (-0.11, 0.90, 0.0),
"hip_l": (0.11, 0.90, 0.0),
"knee_r": (-0.11, 0.49, 0.0),
"knee_l": (0.11, 0.49, 0.0),
"sail": (0.0, 1.46, -0.2),
}
# Part -> (the joint it turns about, the joint it hangs from or None for the root).
PARTS = {
"pelvis": ("hips", None),
"torso": ("waist", "hips"),
"head": ("neck", "waist"),
"upper_arm_r": ("shoulder_r", "waist"),
"upper_arm_l": ("shoulder_l", "waist"),
"forearm_r": ("elbow_r", "shoulder_r"),
"forearm_l": ("elbow_l", "shoulder_l"),
"thigh_r": ("hip_r", "hips"),
"thigh_l": ("hip_l", "hips"),
"shin_r": ("knee_r", "hip_r"),
"shin_l": ("knee_l", "hip_l"),
"sail": ("sail", None),
}
# Where the right hand closes on a grip, and the left on a support, in Godot axes.
HAND_R = (-0.24, 0.86, 0.03)
HAND_L = (0.24, 0.86, 0.03)
# Placeholder colours for the player's own oilskin, so the .mtl files look right.
OWN = {"COAT": items.PALETTE["OILSKIN"], "COAT_DARK": tuple(c * 0.72 for c in items.PALETTE["OILSKIN"])}
def b(x, y, z):
"""Godot (x, y, z) to Blender (x, -z, y)."""
return (x, -z, y)
def own_materials():
for name, rgb in OWN.items():
made = bpy.data.materials.new(name)
made.use_nodes = True
linear = tuple(items.srgb_to_linear(c) for c in rgb)
made.node_tree.nodes.get("Principled BSDF").inputs["Base Color"].default_value = linear + (1.0,)
made.diffuse_color = linear + (1.0,)
def built(make):
"""Runs a builder and returns the objects it added."""
before = set(bpy.data.objects)
make()
return [obj for obj in bpy.data.objects if obj not in before]
# --- Parts, built where they stand in the rest pose (Godot axes via b()) ---------
def pelvis():
# The coat's skirt, flaring a little, over a tarred belt.
items.tube(0.25, 0.34, b(0.0, 0.84, 0.0), "COAT", axis="Z", sides=8, radius2=0.205)
obj = bpy.context.active_object
obj.scale = (1.0, 0.72, 1.0)
items.tube(0.21, 0.05, b(0.0, 1.0, 0.0), "TAR", axis="Z", sides=8)
bpy.context.active_object.scale = (1.0, 0.74, 1.0)
items.box((0.07, 0.02, 0.05), b(0.0, 1.0, 0.155), "GILT", bevel=0.0)
def torso():
items.tube(0.205, 0.46, b(0.0, 1.25, 0.0), "COAT", axis="Z", sides=8, radius2=0.235)
bpy.context.active_object.scale = (1.0, 0.68, 1.0)
# The coat's front edge and its toggles.
items.box((0.03, 0.012, 0.44), b(0.0, 1.25, 0.158), "COAT_DARK", bevel=0.0)
for index in range(3):
items.box((0.06, 0.02, 0.016), b(0.0, 1.12 + index * 0.12, 0.166), "BARK", bevel=0.0)
# A turned-up collar.
items.tube(0.13, 0.08, b(0.0, 1.49, -0.01), "COAT_DARK", axis="Z", sides=8, radius2=0.15)
# A rolled bedding bundle across the back, tied with tarred cord.
items.tube(0.075, 0.42, b(0.0, 1.38, -0.21), "TANNED_SAIL", axis="X", sides=8)
for side in (-1.0, 1.0):
items.ring(0.078, 0.01, b(side * 0.13, 1.38, -0.21), "TAR", axis="X")
items.box((0.05, 0.02, 0.36), b(-0.1, 1.3, -0.17), "TAR", rot=(0.0, math.radians(-28), 0.0), bevel=0.0)
def head():
items.tube(0.055, 0.1, b(0.0, 1.53, 0.0), "SKIN", axis="Z", sides=8)
items.ball(0.115, b(0.0, 1.635, 0.01), "SKIN", rings=6, segments=10)
items.box((0.03, 0.04, 0.05), b(0.0, 1.63, 0.125), "SKIN", rot=(math.radians(10), 0.0, 0.0), bevel=0.005)
for side in (-1.0, 1.0):
items.box((0.026, 0.01, 0.016), b(side * 0.045, 1.665, 0.108), "INK", bevel=0.0)
# A short, square beard.
items.box((0.17, 0.08, 0.09), b(0.0, 1.56, 0.07), "BARK", bevel=0.01)
# The sou'wester: a soft crown and a brim that runs long down the back.
items.tube(0.128, 0.11, b(0.0, 1.735, -0.005), "COAT", axis="Z", sides=10, radius2=0.1)
bpy.ops.mesh.primitive_cylinder_add(vertices=12, radius=0.2, depth=0.022, location=b(0.0, 1.69, -0.045))
brim = bpy.context.active_object
brim.scale = (1.0, 1.22, 1.0)
brim.rotation_euler = (math.radians(-9), 0.0, 0.0)
items.finish(brim, "COAT_DARK")
def upper_arm(side):
x = side * 0.225
items.ball(0.075, b(x, 1.41, 0.0), "COAT", rings=5, segments=8)
items.tube(0.068, 0.27, b(side * 0.23, 1.28, 0.0), "COAT", axis="Z", sides=8, radius2=0.06)
def forearm(side):
x = side * 0.236
items.tube(0.06, 0.2, b(x, 1.04, 0.0), "COAT", axis="Z", sides=8, radius2=0.054)
items.tube(0.064, 0.05, b(x, 0.93, 0.0), "COAT_DARK", axis="Z", sides=8)
# A mitten: the hand closed on nothing, its thumb toward the front.
items.box((0.07, 0.085, 0.1), b(x, 0.86, 0.015), "SKIN", bevel=0.015)
items.box((0.025, 0.035, 0.05), b(x - side * 0.03, 0.885, 0.055), "SKIN", bevel=0.006)
def thigh(side):
items.tube(0.085, 0.42, b(side * 0.11, 0.7, 0.0), "TAR", axis="Z", sides=8, radius2=0.075)
def shin(side):
x = side * 0.11
items.tube(0.07, 0.22, b(x, 0.38, 0.0), "TAR", axis="Z", sides=8)
# A sea boot to below the knee, with its top turned down, and its foot.
items.tube(0.086, 0.26, b(x, 0.16, 0.0), "TAR_WEATHERED", axis="Z", sides=8, radius2=0.08)
items.tube(0.094, 0.05, b(x, 0.3, 0.0), "TAR", axis="Z", sides=8)
items.box((0.13, 0.25, 0.08), b(x, 0.04, 0.05), "TAR_WEATHERED", bevel=0.02)
def sail():
# A canvas wing on two spars, swept back and bowed up at the tips, hung from a
# yoke over the shoulders.
for side in (-1.0, 1.0):
bpy.ops.mesh.primitive_cube_add(size=1.0, location=b(side * 0.66, 2.06, -0.08))
panel = bpy.context.active_object
panel.scale = (1.3, 0.85, 0.012)
panel.rotation_euler = (math.radians(4), math.radians(side * -9), math.radians(side * 12))
items.finish(panel, "CANVAS")
bpy.ops.mesh.primitive_cube_add(size=1.0, location=b(side * 0.62, 2.065, -0.1))
band = bpy.context.active_object
band.scale = (1.2, 0.12, 0.016)
band.rotation_euler = (math.radians(4), math.radians(side * -9), math.radians(side * 12))
items.finish(band, "OCHRE_RED")
items.tube(0.02, 1.36, b(side * 0.66, 2.1, 0.33), "PLANK", axis="X", sides=6,
rot_extra=(0.0, math.radians(side * -9), math.radians(side * 12)))
# The lines from the wing down to the yoke.
items.tube(0.007, 0.62, b(side * 0.3, 1.78, -0.12), "TAR", axis="Z", sides=4,
rot_extra=(0.0, math.radians(side * 30), 0.0))
items.tube(0.024, 0.95, b(0.0, 2.08, -0.1), "PLANK", axis="Y", sides=6)
items.box((0.36, 0.05, 0.05), b(0.0, 1.5, -0.2), "PLANK", bevel=0.008)
BUILDERS = {
"pelvis": pelvis,
"torso": torso,
"head": head,
"upper_arm_r": lambda: upper_arm(-1.0),
"upper_arm_l": lambda: upper_arm(1.0),
"forearm_r": lambda: forearm(-1.0),
"forearm_l": lambda: forearm(1.0),
"thigh_r": lambda: thigh(-1.0),
"thigh_l": lambda: thigh(1.0),
"shin_r": lambda: shin(-1.0),
"shin_l": lambda: shin(1.0),
"sail": sail,
}
def export_part(name, objects):
"""Moves a part so its joint is at the origin and writes it as an OBJ."""
joint = b(*JOINTS[PARTS[name][0]])
bpy.ops.object.select_all(action="DESELECT")
for obj in objects:
obj.location = (obj.location[0] - joint[0], obj.location[1] - joint[1], obj.location[2] - joint[2])
obj.select_set(True)
bpy.ops.wm.obj_export(
filepath=os.path.join(OUT_DIR, name + ".obj"), export_selected_objects=True,
apply_modifiers=True, export_uv=False, export_normals=True, export_materials=True,
export_triangulated_mesh=True, forward_axis="NEGATIVE_Z", up_axis="Y",
export_object_groups=False, export_material_groups=False, path_mode="STRIP",
)
for obj in objects:
obj.hide_set(True)
def main():
os.makedirs(OUT_DIR, exist_ok=True)
items.clear_scene()
own_materials()
triangles = 0
for name, make in BUILDERS.items():
objects = built(make)
for obj in objects:
obj.data.update()
triangles += sum(len(poly.vertices) - 2 for poly in obj.data.polygons)
export_part(name, objects)
print("figure part %s done" % name)
info = {
"generator": "tools/models/figure.py",
"joints": {name: [round(v, 4) for v in at] for name, at in JOINTS.items()},
"parts": {name: {"joint": joint, "parent": parent} for name, (joint, parent) in PARTS.items()},
"hand_r": list(HAND_R),
"hand_l": list(HAND_L),
"height": 1.8,
"triangles_before_bevel": triangles,
}
with open(os.path.join(OUT_DIR, "figure.json"), "w") as out:
json.dump(info, out, indent="\t", sort_keys=True)
out.write("\n")
if __name__ == "__main__":
main()
+2 -1
View File
@@ -476,4 +476,5 @@ def main():
print("item %s done" % item_id)
main()
if __name__ == "__main__":
main()