ToonGenerator

Independent Godot 4.7 studio for stylized low-poly rigged characters and entities, with EnC as its official reference game. Open project.godot and run studio.tscn, or launch godot --path ToonGenerator from the EnC folder.

The studio's layout, tabs, viewport, lighting and dialogs are saved scene nodes authored through Godot MCP. Controllers connect those controls to editable character data; the ear inspector adds its compact parameter controls at runtime.

The studio and installable Godot addon now share one core. EnC uses the addon to generate rigged humans from inherited colors and proportions, with ToonGenerator supplying their animations. Self-contained exports remain supported. See the integration contract and addon installation/API.

Simple character designer

The creator opens with an unclothed Male toon base. Male, Female, and Quadruped are available under New… alongside the example library; Open loads saved designs. The new human bases are original continuous surfaces, with approximately 6,750 body triangles, rounded limbs, a large toon head, and a 21-joint rig. They are stylized anatomical bases without explicit anatomy. The older Human blank canvas remains available through the scripting API for compatibility.

The left appearance menu groups features into Body & identity, Facial features, Hair & headwear, and Clothing & details. Select a group, then its feature; no long category list is needed. The right inspector has four compact sections instead of one long form:

• Style: visual choices, hover preview, click to commit.
• Shape: connected body proportions grouped as Head (size, width, depth), Torso (shoulders, chest, waist, belly, length) and Limbs (arm thickness and length, hand size, leg thickness and length, foot size), or feature transforms for other categories. Head, hand and foot sliders scale about the skull base, wrists and ankles so joints stay attached; together they reach the Wind Waker silhouette, where a head is close to half the character's height. Ears have paired rotation, length, and tilt controls that keep their attachment roots fixed.
• Color: colors the selected item (all of its pieces by default), with a selector for individual pieces. Body exposes global skin tone; Eyes exposes iris color for compatible styles. Item colors preserve skin, unrelated clothing, and facial artwork. Garments also offer a Stripes pattern: even horizontal bands of any width, gap and offset that continue around every piece of the item (torso and sleeves alike) in an exact stripe color.
• Files: character variants, reusable outfits/items, and Godot/GLB/OBJ export.

There are eleven eye, ten mouth, and ten ear styles, with matching thumbnails; the Wind Waker eye style is a wide rounded oval under a heavy upper lid with a large dark iris, matching the reference eye planes. Eye and mouth styles remain independent. Blank styles and existing speech expressions remain available.

The Shape tab under Body & identity shapes the silhouette one region at a time: Head (size, width, height, depth, neck length and width), Face (jaw width, chin length, cheek fullness, brow height), Torso (shoulders, chest, waist, hips, belly, torso length), Arms (upper arm, forearm, arm length, hand size) and Legs (thigh, calf, leg length, foot size). Every control is a continuous warp of the rest shape that moves the joints, the garments and the painted face with it, so a saved value is absolute and can be set back to 100% exactly. Quadrupeds show only the regions their rig has.

The Scene selector above the preview offers Starry sky, Grassland / savannah, Single color, Island, and Playground. Island adds a grassy clearing, sandy beach, palm trees, and turquoise ocean. Playground loads playground.tscn (the side-on animation course with its runtime-generated characters and goal-planning autopilot) into the preview world and stands the character you are editing on the island at playground scale, so the model and its animations can be adjusted while the planner keeps running. The studio camera, lighting presets and undo keep working; the course sun lights the stage. The character you are editing becomes the AI player and every edit reaches it mid-run; the dock above the preview holds the camera presets (3rd person, orthogonal 2D, top down, free orbit), pause and time scale, and the Overlay toggle for the autopilot read-out. The playground's own keys apply inside the viewport too (1–5/0 time scale, V camera, T takes the controls, R restarts). A new session always starts on the island. The adjacent swatch adjusts the scenery tint or solid background color. These settings persist locally and stay out of character exports. Lighting… opens Studio, Soft front, Sunlight, Moonlight, Rim light, and Flat color presets, plus brightness, direction, elevation, shadow fill, and light color controls. Lighting updates the toon body/head shaders and scenery immediately without rebuilding geometry; it remains a preview preference.

Interactive edits prepare body deformation, clothing fitting, mesh arrays, seam normals, and facial projection on a worker thread. The last complete model remains visible and animated until the latest result is ready; superseded requests are discarded. Color pickers reuse protected palette entries, and unchanged atlas textures are reused. Save, undo, and subsequent edits resolve pending proportions correctly. GPU upload and scene installation still happen on the main thread.

The preview bar provides animation selection, Play/Pause, Rest pose, and Blink. More… opens the installed Mixamo packs in Advanced → Animate. The new bases include Idle, Walk, Run, Wave, T_Pose, Joint_Check, and Spine_Check. Spine_Check demonstrates connected pelvis/chest/neck/head bending; corrected walking/running knees alternate with positive anatomical flexion and coordinated ankle roll. New-base forefeet now blend into toe bones for heel strike and push-off.

Body proportions deform the surface and rig together. New-base head/body transforms stretch neighboring geometry using a continuous spatial deformation. The connected base cannot be deleted, changed into a primitive, or rebound from the inspector. Global skin-tone changes and slider drags are undoable. Head/body boundary normals are smoothed together. Garments are fitted over the new torso and upper arms to reduce skin showing through clothing.

Additional original wardrobe options include shorts, a beanie, glasses, and a cape. Stock styles on the new bases retain their authored colors. Existing projects retain their own geometry and palette; legacy modular examples are not automatically remeshed.

See the 1.0 audit and validation notes for scope, evidence, and remaining limitations, the September 2026 audit for the bug fixes, optimizations and the studio theme overhaul, and the UI/UX QA report for the window-scaling policy (720p to 4K ultrawide) and the studio workflow-integrity fixes. The theme is generated by tools/build_studio_theme.gd; regenerate it after editing that script rather than hand-editing studio_theme.tres. The repository is hosted on Forgejo at git.techeron.com; connecting this repo to Forgejo has the from-scratch procedure, including why HTTPS is the working transport from this machine.

Toon Link and Niko rebuilt from the blank Male base using only the creator UI are included as ToonLink_Studio and Niko_Studio in the project library; tools/replay_character_recipes.gd replays the recorded clicks and renders review shots.

Advanced mode

Switch the mode selector to Advanced for the original detailed tools:

• Build: outliner selection and numeric position, rotation and size; add, copy, mirror, rename and delete accessory parts. Connected-base geometry is protected.
• Paint: fill or brush triangles on the model; edit the shared indexed palette. Brush detail depends on mesh density.
• Rig: click a joint marker in the viewport, then edit its pivot or binding. Human models have 21 joints and blended elbow/wrist/knee/ankle regions. Rebinding a part replaces those weights with a single-joint binding; freehand weight painting and IK are not implemented.
• Animate: body clip selection, rotational keys, duration and loops, plus the Joint_Check bend preview. Clips are in place.
• Face: pencil, eraser, fill, eyedropper, mirror strokes, grid, onion skinning, zoom/pan and separate eye/mouth playback. Index zero is transparent.
• Export: native Godot, GLB or OBJ export and editable project saving.

Switching modes preserves the design. Undo/redo retains 80 document snapshots. Right drag orbits; middle drag pans; wheel zooms. Front, Side and Fit reset the view.

Choosing and tuning motions

Simple mode's Motion section replaces the designer panel with the animation mapper. Pick a clip for each activity slot from the 189-entry Mixamo catalog, tune it for this model — playback speed, loop, and per-bone X/Y/Z rotation offsets — and review it three ways: Play clip on the studio stage, Play sequence to walk every mapped slot in order, or Playground, which makes the character the AI player so the mapped clips are what the course runs. The map travels in the .toon.json and is compiled into document.clips, so an exported scene carries exactly the motions that were reviewed. Mapped Map_* clips are read-only in the Animate tab, because the next mapping edit regenerates them. Full detail in docs/animation-mapper.md.

Save As and reusable files

Save As lets you choose editable project (.toon.json), Godot scene (.tscn) or glTF (.glb) or Wavefront (.obj) using its file-type selector, or type a supported extension. The filename suffix follows the chosen format. Exporting does not change the editable project's save path or clear its unsaved changes. Save / Ctrl+S saves the current project; for a new character it opens Save As.

Outfits use .outfit.toon.json; individual parts use .item.toon.json. Use their Load buttons to add them to a character. Normal project Open prevents accidentally replacing a character with a component file.

Final mesh and replaceable facial textures

The designer keeps source parts editable, but native character exports compile them into one skinned MeshInstance3D (CharacterMesh), one ArrayMesh surface and one ShaderMaterial. Body, clothing and items share that mesh; eyes and mouths are projected texture layers on the existing head triangles. No facial mesh planes are generated. Exports index identical vertex attributes to reduce duplication. The new male/female body surfaces are closed and geometrically connected; OBJ shares coincident position indices across head/body materials. Accessories and legacy examples may contain intersecting shells, and hidden triangles are not automatically removed.

Native Godot exports contain three independently replaceable textures: body_texture (256×256 palette), eyes_texture (1024×64, eight horizontal cels), and mouth_texture (768×64, six horizontal cels). Characters without facial passes only need the body texture. Body painting retains its indexed palette; facial pixels can be painted in the studio and replaced independently in a game.

The same native material handles cel shading and transparent facial graphics. Separate EyeAnimations and MouthAnimations players animate integer shader parameters eye_frame and mouth_frame, without changing body animation. The material is local to each scene instance, so one character's expression or texture replacement does not affect another instance. Textures remain shared until you replace them.

var material: ShaderMaterial = character.get_node("CharacterMesh").material_override
material.set_shader_parameter("eyes_texture", preload("res://faces/my_eyes.png"))
material.set_shader_parameter("mouth_texture", preload("res://faces/my_mouth.png"))
# Use 1 for a single expression image, or the column count of your horizontal strip.
material.set_shader_parameter("eye_columns", 1)
material.set_shader_parameter("mouth_columns", 1)
# Stop only the relevant facial loop when setting a frame manually.
character.get_node("EyeAnimations").stop()
material.set_shader_parameter("eye_frame", 0)

Use transparent backgrounds for custom facial images. Keep the eye pair/eyebrow composition aligned within its frame. GLB exports contain one skinned mesh with Body and Head material surfaces. GLB and OBJ bake the selected expression into an opaque Head texture on the existing head triangles. Their embedded facial expression is static. Portable exports additionally write <name>_face/eyes.png, mouth.png, and animations.json, preserving independent RGBA strips, clip timing, and projection frames. Recreate layer compositing and frame playback in the destination engine, or use native Godot export for ready-to-use facial playback.

The shipped examples/HumanLibrary.tscn contains eight single-mesh humans sharing one body palette texture, with separate eye and mouth strips per character. Individual native exports are self-contained.

Hair and hats are tagged as layers. Fitting projects exposed hair surfaces outside the head profile, keeps buried roots inside, and seats hats below the hair's highest point. Source fit settings control hair_clearance, hat_clearance and hat_seat. This is profile-based fitting, not a general collision solver; heavily reshaped or rotated heads and accessories need visual adjustment.

Reference studies and EnC import

The Link study has rounded shoulders, slimmer curved sleeves, continuously tapered forearms and rebuilt palm-down hands with aligned wrists, four fingers and forward thumbs, a broad cheek silhouette, pointed ears, swept fringe, pointed cap, tunic and spiral buckle. The other humans explore slender, tall, broad and child proportions. These are reconstructed starting studies, not extracted Nintendo assets or finished replicas. References and Aseprite UI research are recorded in references/README.md.

• examples/ToonLink.toon.json: editable source.
• examples/ToonLink.tscn: native export with embedded cel shader, skin and all three animation players.
• examples/ToonLink.glb: one skinned mesh, replaceable body/face textures and body clips.
• examples/HumanLibrary.tscn: eight single-mesh humans with a shared body palette and separate facial textures.
• previews/LinkStudy.tscn: MCP-authored review scene.

Export to another Godot project

1. Open Export → Export for Godot (.tscn).
2. Save the file into the destination project's folder, or copy it there afterward. Only that .tscn file is needed.
3. In the destination Godot editor, drag the file from the FileSystem dock into a 3D scene.

The exported file embeds its single mesh, body/eye/mouth textures, toon shader, skin, skeleton and animation libraries. It needs no ToonGenerator scripts, addon, source JSON or folder structure. Verified in a separate Godot 4.7.2 project containing only the exported scene and a test script; earlier Godot versions have not been verified.

Coordinates use meters, +Y up and +Z forward. The root is a visual Node3D; add your game's controller and collision nodes around it as needed. Body animation is on Animations, expressions on EyeAnimations and MouthAnimations:

# character is an instance of the exported character scene.
character.get_node("Animations").play("Walk")
character.get_node("EyeAnimations").play("Blink")
character.get_node("MouthAnimations").play("Talk")

Multiple instances animate independently, including their facial expressions, while initially sharing their embedded textures. The separate editable .toon.json source is only needed for further editing in ToonGenerator.

A build machine can produce the same scene without the studio UI: runtime/appearance_bake.gd takes one runtime appearance request (plus an optional list of motion-library ids) and returns a packed scene, and tools/export_appearance.gd wraps it for the command line. It accepts the core's full proportion set, so a consumer that composites its own armour can dial the body inside gear authored for another mesh. See docs/ENC_INTEGRATION.md.

GLB retains one mesh with separate texture surfaces, body animation and the selected static facial expressions. glTF does not carry these Godot UV-offset facial animation tracks or the cel shader; recreate expression playback and toon shading in the destination renderer. Empty clips may be omitted by glTF.

Animation Playground

playground.tscn is a Wind Waker styled side-on course built for watching animation in motion. Run it with godot --path ToonGenerator playground.tscn, or open it in the editor and press Play Scene.

Every character in it is generated at runtime through character_service.gd and driven only by semantic activity and simulation time, so what you are judging is the same playback path a game gets. The camera sits square to the side on a long lens and the characters act on one plane, so the run reads as a 2D scene.

The course is shaped so the interesting transitions happen on their own. The player spawns on a big crate at the left, steps across onto a drifting raft, rides it out over the hill, leaps to a stone spire on the right, draws steel and fights the animal patrolling it, steps off into a fall long enough to demand a roll, sprints back along the beach and up the hill, and takes the lip at a full sprint to land home on the crate. The sprint is not decoration: the last jump is outside the running arc and inside the sprinting one. Behind the action a woodcutter moves a stack of six logs from one pile to the other, one at a time — walk over, crouch and lift, carry, kneel and set down — and works the stack back once the first pile is empty, so the everyday motion pools stay visible beside the action pools in the same light. The piles are log_pile.tscn instances placed in the scene; drag them and the chore follows.

The sword and the shield are item scenes (scenes/playground/sword.tscn, shield.tscn) built on the addon's item.gd: each names the socket it is held in and the one it is stowed on, with both poses authored in the inspector. Opening a chest puts its prize straight into use — the draw hands the blade to the right hand and the shield to the left arm — and the same scene fits any generated character, which is the mechanism the addon offers games for their own props. Hand props follow one convention, measured off the rig's own hand: +X runs along the arm through the fingertips, +Y leaves the back of the hand and +Z is the grip axis a blade runs out of the fist along, past the thumb. The sword therefore runs its blade down the grip axis — the axis a real fist closes around — with the flat lying against the palm, and the shield turns its face off the back of the hand. That is why the shield faces the enemy when the guard goes up instead of presenting its edge, and why a swing cuts with the blade's edge: the tip travels along the hand's +X while the blade itself stays almost perpendicular to the stroke, instead of pointing up out of the back of the fist.

Damage is drawn over the body that took it. Every enemy — the spire beast, the pack and Ganondorf — carries a billboard bar that reads that enemy's own health, rides above its head at the height of its own bounds, and only appears once it has been hurt, so the overlay stays a read-out rather than a second HUD. It flashes on the hit and drains from the far end, and it retires when the enemy dies or heals.

Letting it run itself

Watching a transition is hard while playing it, so the run is also a planning problem. playground_pilot.gd is a small goal-oriented planner: each way of getting from one part of the island to another is an action with preconditions and effects, and it searches for the shortest sequence satisfying "back on the crate with the beast dead". It re-plans from what it observes, so being knocked off the spire produces a real recovery — walk back up the flank, take another run-up — rather than a broken script, and the animation you were trying to judge comes round again on its own. The autopilot and a human fill the same intent, so the controller cannot tell which is driving. Press T to take over or hand back.

The overlay names, per character, the semantic activity requested and the authored take the motion library returned, and lists the autopilot's current plan with the step it is on, which is what a review actually needs.

Key
A / D or ← →	move
Shift / Ctrl	sprint / walk
Space, J	jump, attack
K, L	guard, dodge roll
Q	draw the bow — an upper-body overlay that plays over the walk or run
T	autopilot on/off
1 2 3, 4 5, 0	speed 1x / .5x / .25x, 2x / 4x, pause
V	camera preset: 3rd person, orthogonal (2D platformer), top down, free
RMB, wheel, F	orbit and zoom the free camera, back to the side view
R, F1-F6	restart the run, jump to crate / raft / spire / beach / islet / arena

Every one of those controls is an Input Map action — pg_* in the playground, studio_* in the studio — stored in project.godot, so a key can be remapped in the editor without touching a script. tests/test_input_map.gd holds both halves of that rule: the actions exist and are bound to the documented defaults, and no script under scripts/ reads a raw KEY_*, mouse button or button mask.

Slow motion and the camera presets are the point of the tool: set .25x, cycle V to the third-person view, and watch a landing or a combo settle. F1-F6 skip to a stage of the course so one transition can be replayed without running the whole lap. Inside the studio the same presets and speeds are in the dock above the preview, and the character being edited is the AI player: every edit is rebuilt and swapped into the running actor mid-lap, pack and all.

Validation and regeneration

godot --headless --path ToonGenerator --script tests/test_pipeline.gd
godot --headless --path ToonGenerator --script tests/test_designer.gd
godot --headless --path ToonGenerator --script tests/test_save_workflow.gd
godot --headless --path ToonGenerator --script tests/test_components.gd
godot --headless --path ToonGenerator --script tests/test_designer_workflow.gd
godot --headless --path ToonGenerator --script tests/test_playground.gd
godot --headless --path ToonGenerator --script tests/test_playground_props.gd
godot --headless --path ToonGenerator --script tests/test_actor_overlay.gd
godot --headless --path ToonGenerator --script tests/test_input_map.gd
godot --headless --path ToonGenerator --script tests/test_export_appearance.gd
godot --headless --path ToonGenerator --script tests/test_animation_map.gd
godot --headless --path ToonGenerator --script tests/test_animation_mapper.gd
godot --headless --path ToonGenerator --script tests/test_ui_layout.gd
godot --headless --path ToonGenerator --script tests/test_ui_navigation.gd
godot --headless --path ToonGenerator --script tests/test_pattern_stripes.gd
godot --headless --path ToonGenerator --script tests/test_character_recipes.gd
python ToonGenerator/tests/test_portability.py
python ToonGenerator/tools/build_human_library.py
godot --headless --path ToonGenerator --script tools/export_examples.gd

Validation includes the 2,148-check export/rig suite, 277 designer checks, 23 Save As checks, 15 reusable-component checks, 404 end-to-end designer workflow checks, 153 playground checks, 74 prop, hold and damage-read-out checks, 23 appearance-bake checks, 99 animation-mapper checks, 9,256 runtime-motion checks, 23 upper-body-overlay checks and 125 UI layout/navigation checks, plus 107 Input Map checks that no script reads a raw key. The playground suite proves the course's own claims with real physics: every gap is inside the jump arc, the last one is outside the running arc, no ground slope traps the player, and the planner completes an unattended lap through the states the level was shaped to produce. Tests cover document validation, save/load, skin bindings, animated poses, native/GLB round trips, CPU-backed texture preservation, independent facial playback, indexed drawing, shared texture identity, mesh painting, mirroring and undo/redo. Artifacts go to /tmp/toongenerator-tests; override with TOONGENERATOR_TEST_OUTPUT. Verified with Godot 4.7.2.

The Python modeling tools replace shipped examples, so save personal variants elsewhere. Run tools/annotate_projects.gd afterward to attach and verify designer categories without changing geometry or paint. The export helper reads saved examples rather than rebuilding their authoring data. The Python tools author mesh source data offline. Preserve the installed Godot AI addon for MCP connectivity.

Humanoid animation contract

The 21-joint hierarchy is root → hips → body → neck → head, with shoulder → upper arm (arm_L/R) → elbow → wrist chains and hip (leg_L/R) → knee → ankle → toe chains. Elbow and knee vertices blend across adjacent joints; inverse bind transforms preserve the T-pose. Mesh reindexing preserves the original paint and skin vertex correspondence, preventing uneven deformation around joints. Hands are authored directly in that pose, with palms facing down and thumbs toward the character's front (+Z). Layering happens in the actor rather than through an AnimationTree: a 16-actor benchmark (tools/bench_actor.gd) measured the actor's own blend at 0.036 ms per actor-frame against 0.054 ms for an AnimationNodeBlendTree with Blend2 and a synchronised position track (0.371 against 0.606 ms under churn, same retained memory), and the tree was the only route that popped the pose when a clip was swapped mid-blend. The addon README documents the two layer keys, overlay/overlay_weight and set_activity_clips.

The seven supplied Mixamo packs are available in Advanced → Animate → Mixamo motions. Choose a pack and clip, then add it to the current human character. In-place conversion preserves vertical hip motion; selected clips save with the character and export to native Godot/GLB. See Mixamo usage and rig review for conversion details, rebuild commands and remaining finger/spine limitations. Open examples/ToonLinkMixamo.toon.json or examples/PersonMixamo.toon.json for ready-to-play idle, walk, run and jump studies.

OBJ export for Mixamo

Choose Save As → Wavefront OBJ + Mixamo ZIP, or Advanced → Export → Export OBJ + Mixamo ZIP. The export uses the model's rest pose (T-pose for humans), regardless of the preview animation.

For Character.obj, the exporter creates:

• Character.obj: one object with triangulated geometry, UVs and normals; +Y up, meter units.
• Character.mtl and Character_assets/: body and opaque head PNG textures.
• Character_mixamo.zip: the complete package with relative texture references, ready for upload. Names containing spaces use an underscored material/asset stem.

On Mixamo, sign in, choose Upload Character, and upload the generated ZIP to include textures. Place its rigging markers and preview the desired animation. OBJ carries neither bones nor animation; Mixamo creates a new rig. Facial expressions are static in this format, and the Godot cel shader does not transfer. Keep the native .tscn for the game-ready rig and independent facial controls.

OBJ adds no facial triangles or transparent cards. The selected eye and mouth drawing is baked onto the head texture; it therefore works in viewers that ignore opacity maps.

The OBJ structure, normals, textures and ZIP contents are tested locally. Mixamo acceptance and animation fitting still need testing through a signed-in account, especially for exaggerated proportions. Mixamo's auto-rigger targets humanoids; Quadruped OBJ export is for general modeling tools.

Adobe's OBJ/MTL/texture ZIP instructions.

godot --headless --path ToonGenerator --script tests/test_obj_export.gd