renpy-rigging

A 2D skeletal rigging, posing, and animation system for Ren'Py — including a full visual editor and a cue-based film production pipeline.

Why renpy-rigging?

Ren'Py games typically display characters as static sprites — a handful of pre-drawn poses swapped in and out. If you want a character to breathe, gesture, walk across a room, or dance with a partner, you're either drawing every frame by hand or leaving it out.

renpy-rigging gives Ren'Py characters a skeleton. Separate PNG body parts connect at joints that rotate, scale, and blend between poses — the same technique 2D game engines use, but designed specifically for Ren'Py's visual novel workflow. You build characters in a visual editor, and the same rendering code runs in your game. No export step, no format conversion, no drift between what you author and what players see.

What you see in the editor is exactly what ships in your game.

What You Can Do

Animate characters from reusable parts

Draw body parts as individual PNGs, connect them at joints, and create a library of named poses. Blend between poses, loop idle animations, layer breathing over walking — all from the same set of art assets. Poses are composable deltas, so a "wave" pose only stores the arm rotation, not the whole body.

Dress and equip characters at runtime

Swap clothing with overlays (a shirt replaces the torso art) or attach independent objects with attachments (a gun docks to a hand joint with its own skeleton and animations). Both use named slots for clean mutual exclusion — equipping a tommy-gun automatically holsters the pistol.

Build complete environments

Compose backgrounds, layered props, placed characters, and ambient sound into scenes. Define named locations and scripted actions (curtain draws, day-to-night transitions) that trigger from your game script.

Direct multi-character sequences

The Film Studio uses a cue-based model inspired by theatrical lighting cues: cues run in sequence, tracks within a cue run in parallel, steps within a track run in sequence. Choreograph synchronized movement, camera pans, title cards, scrolling credits, and soundtracks — then play them in real time in Ren'Py or export to GIF/MP4.

Author everything visually

The Ren'Py Rigging Studio is a Ren'Py app with four screens — rig/pose editing, animation timeline, scene composition, and clip sequencing. Mouse-driven manipulation with keyboard nudging, undo/redo, and live preview. Because the editor uses the same renderer as your game, there's no WYSIWYG gap.

Quick Start

Install the runtime

pip install renpy-rigging

Load and display a character

init python:
    from renpy_rigging import RigRenderer

    vince = RigRenderer.from_directory("characters/vince")

# Static pose
show expression vince.show_pose("neutral") as vince:
    xalign 0.5 yalign 0.7

# Looping animation
show expression vince.play_animation("idle", loop=True) as vince:
    xalign 0.5 yalign 0.7

Use overlays and attachments

vince.add_overlay("broadway-brawlers-shirt")
vince.add_attachment("tommy-gun")
vince.set_attachment_pose("tommy-gun", "firing")

Load a scene

init python:
    from renpy_rigging import SceneManager, register_channels

    register_channels()
    scene_mgr = SceneManager(os.path.join(renpy.config.gamedir, "scenes"))
    scene_mgr.register_images()

$ scene_mgr.show("speakeasy")

See the Ren'Py Integration Guide for full setup and usage.

Asset Directory Layout

game/
  characters/
    vince/
      rig.json           # Skeleton and parts
      poses.json         # Named poses (deltas from neutral)
      animations.json    # Pose sequences with timing
      overlays.json      # Layered clothing/accessories
      attachments.json   # Bound props/weapons
      parts/             # PNG body part images
      overlays/          # Overlay images per set
      sounds/            # Sound effects
  attachments/
    tommy-gun/
      rig.json           # Attachment's own skeleton
      poses.json
      animations.json
      parts/
  scenes/
    speakeasy/
      scene.json         # Background, layers, placed entities
      parts/             # Scene prop images
  clips/
    stage-show/
      clip.json          # Cue-based multi-character sequence

All data is stored as human-readable, hand-editable JSON. See Data Formats for the specification of each file type.

Documentation

For Users

• Character Authoring Guide — art preparation through animation
• Ren'Py Integration Guide — installing and using renpy-rigging in your game
• Character Design Tutorial — building Clara step-by-step
• Film Clip Tutorial — building the stage-show clip

For Editor Users (Studio)

• Studio Overview — navigation and shared UI
• Rig & Pose Editor — skeleton and pose authoring
• Timeline Editor — animation sequencing
• Scene Editor — environment composition
• Film Studio — clip production

For Developers

• Architecture — system components, rendering pipeline, and design principles
• Data Formats — JSON specification for every asset type
• Demo Overview — sample game and bundled assets

License

MIT License — see LICENSE for details.