Metadata-Version: 2.4
Name: renpy-rigging
Version: 0.5.3
Summary: A 2D skeletal rigging, posing, and animation system
Project-URL: Homepage, https://github.com/Masked-Fox-Productions/renpy-rigging
Project-URL: Repository, https://github.com/Masked-Fox-Productions/renpy-rigging
Project-URL: Documentation, https://github.com/Masked-Fox-Productions/renpy-rigging#readme
Author: Aaron
License-Expression: MIT
License-File: LICENSE
Keywords: 2d,animation,game-dev,renpy,rigging,skeletal,visual-novel
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.8
Provides-Extra: test
Requires-Dist: pytest>=7.4.0; extra == 'test'
Description-Content-Type: text/markdown

# 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

```bash
pip install renpy-rigging
```

### Load and display a character

```python
init python:
    from renpy_rigging import RigRenderer

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

```renpy
# 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

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

### Load a scene

```python
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()
```

```renpy
$ scene_mgr.show("speakeasy")
```

See the [Ren'Py Integration Guide](docs/guides/renpy-integration.md) 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](docs/data-formats/) for the specification of each file type.

## Documentation

### For Users
- [Character Authoring Guide](docs/guides/authoring-guide.md) — art preparation through animation
- [Ren'Py Integration Guide](docs/guides/renpy-integration.md) — installing and using renpy-rigging in your game
- [Character Design Tutorial](docs/tutorials/character-design-tutorial.md) — building Clara step-by-step
- [Film Clip Tutorial](docs/tutorials/film-clip-tutorial.md) — building the stage-show clip

### For Editor Users (Studio)
- [Studio Overview](docs/studio/overview.md) — navigation and shared UI
- [Rig & Pose Editor](docs/studio/rig-editor.md) — skeleton and pose authoring
- [Timeline Editor](docs/studio/timeline-editor.md) — animation sequencing
- [Scene Editor](docs/studio/scene-editor.md) — environment composition
- [Film Studio](docs/studio/film-studio.md) — clip production

### For Developers
- [Architecture](docs/architecture.md) — system components, rendering pipeline, and design principles
- [Data Formats](docs/data-formats/) — JSON specification for every asset type
- [Demo Overview](docs/demo/overview.md) — sample game and bundled assets

## License

MIT License — see [LICENSE](LICENSE) for details.
