PaperDoll

Introduction

PaperDoll is a 2D puppet runtime for .NET, FNA and MonoGame. It loads rigged cutout puppets in the Inochi2D format (.inp, .inx), evaluates their parameters, deforms their meshes, runs their physics and animations, and draws them through FNA or MonoGame. Several puppets can be on screen at once, each with its own state.

It is an open-source C# port, by behaviour, of Inochi2D and nijilive, with nicxlive as a secondary reference. The originals are written in D and C++. PaperDoll follows their behaviour and structure but is written anew in C#, with no code copied from them. It reads puppets made with Inochi Creator, nijigenerate and Mannequin Character Generator; it doesn’t edit or write them.

Features

The INP1 format

Loads .inp and .inx puppets from Inochi Creator 0.7 and 0.8, nijigenerate and Mannequin Character Generator, with PNG and TGA textures.

Parameters

1D and 2D, all five merge modes, Nearest, Linear and Cubic keyforms, binding transforms, z-sort, opacity, tints and mesh deforms.

MeshGroup deformation

A deformed mesh bends the Parts and nodes below it, triangle by triangle.

Masks and blend modes

Mask and DodgeMask, Mask nodes, all nineteen blend modes (the advanced ones with their real equations), and Composites drawn as layers.

Physics

SimplePhysics pendulums and spring pendulums, stepped per instance, optionally swinging when the game moves the puppet.

Animations

Looping, lead-in and lead-out, every lane interpolation, several at once, without overwriting the values the game sets.

Many puppets at once

One loaded puppet is shared by any number of instances, each with its own time step, parameters, physics and animations.

Fast and lean

No allocations per frame once warmed up. Textures are cropped and packed into atlases, so many parts share a draw call, with optional half-size textures.

Engine-free core

PaperDoll.Core is fully managed, reflection-free, and trimming- and NativeAOT-safe.

Quick look

dotnet add package PaperDoll.FNA        # or PaperDoll.MonoGame, or PaperDoll.Core on its own

var puppet = Puppet.Load("character.inx");      // immutable, shared by its instances
var instance = puppet.CreateInstance();         // one per copy on screen
instance.PlayAnimation("Blink", loop: true);
instance.SetParameterValue(puppet.FindParameter("Head:: Yaw-Pitch")!, new(0.5f, 0));
instance.Update(deltaSeconds);                  // parameters, animations, physics, deformation
renderer.Draw(instance, textures, placement);   // PaperDoll.FNA or PaperDoll.MonoGame

Documentation

• Getting started: From a puppet file to the screen, with parameters, animations, physics and drawing.
• API: The public types, their lifetimes, threading, and the order a game calls them in.
• Features: What PaperDoll supports of the format, how each feature behaves, and what isn’t supported.
• FAQ: Common questions, from which files load to placing puppets and swinging physics.

Packages

PaperDoll.Core

Engine-free and fully managed: the format parser, node tree, parameters, deformers, physics, animations and draw order. Its output per drawable is plain arrays any renderer can use.

PaperDoll.FNA

A thin renderer that draws Core’s output through FNA, with masks, blend modes and texture atlases. Built against FNA 26.10; your game brings FNA itself.

PaperDoll.MonoGame

The same renderer for MonoGame 3.8.6 (DesktopGL or WindowsDX). Your game brings its MonoGame platform package.

Demo and tools

The repository has a demo that shows up to five puppets at once, each placed and scaled on its own, with an ImGui panel of parameter sliders, physics and animation controls, a texture browser and a blend-mode test scene. It runs on FNA or MonoGame, on Windows x64 for now.

Each release on GitHub has the demo as a ready-to-run download, and the paperdoll command-line tool for Windows, Linux and macOS. The tool prints a puppet’s tree, parameters, animations and textures, and reports what in a puppet PaperDoll skips or ignores.

Need puppets to try? Inochi2D’s example models, Aka and Midori, are at github.com/Inochi2D/example-models.

Requirements

• .NET 10 (net10.0)
• FNA 26.10, for PaperDoll.FNA
• MonoGame 3.8.6 with the HiDef profile, DesktopGL or WindowsDX, for PaperDoll.MonoGame

Licence

PaperDoll is released under the BSD 2-Clause licence, the same as the projects it ports. See LICENSE.md for PaperDoll’s notice and the upstream notices, and the attribution page for the projects it builds on.