TRUEWAY
Menu

SpriteOrbit Documentation

From first install to a production bake.

This is the usage layer for SpriteOrbit: how to configure the Blender extension, produce directional sprite actors and understand the files it writes.

Back to SpriteOrbitQuick Start

Contents

Documentation map.

Start with Getting Started for the first bake, then use the remaining sections as a reference.

Getting Started

Requirements, installation and first bake.

Open section

Subjects

Armature, Mesh, Empty hierarchy, Collection and Static Snapshot.

Open section

Animations & Motion

Actions, FBX import, markers, looping and root-motion modes.

Open section

Camera & Framing

Directions, projection, preview and framing.

Open section

Output Passes

Lit Color, Ground Shadow, 2D Normal, Material ID, Emissive, AO, Roughness and Depth.

Open section

Bake What Changed

Selective state/pass rebaking and validated reuse.

Open section

Export Format

Unit manifest, per-state metadata and runtime contract.

Open section

Compatibility & Limits

Tested Blender versions and current integration status.

Open section

Troubleshooting

First checks for common setup and bake problems.

Open section

Getting Started

Install SpriteOrbit and complete a first bake.

SpriteOrbit 1.0 requires Blender 4.2 or newer. Blender 4.5 LTS and Blender 5.1 are the primary tested release families.

Install the release ZIP through Edit > Preferences > Get Extensions > Install from Disk, then open the SpriteOrbit tab in the 3D View sidebar.

  • Select a Subject: Armature, Mesh, Empty hierarchy or Collection.
  • For a rig, add existing Actions or import selected FBX clips. A non-rigged subject can use a Static Snapshot state.
  • Enable the states you need and preview the active state on the 3D subject.
  • Choose direction count, Orthographic or Perspective projection, cell size and framing margin.
  • Use Preview Camera and Measure Framing before a long bake.
  • Choose the required outputs, set the output location and review atlas-size warnings.
  • Use Bake What Changed for the normal included-state workflow. Use Force Rebake Everything only when you deliberately want to rebuild every enabled state.
  • Use Show Preview to inspect Color and enabled data passes without rebaking.

Bundled sample

The release package includes SpriteOrbit_Robot.blend configured with Idle, Walk, Attack and Death.

Output entry point

Each state writes atlas files and per-state JSON; the actor also writes _unit.json as the canonical runtime entry point.

Read export overview

Subjects

Choose what SpriteOrbit owns as one actor.

Subject selection defines which meshes participate in framing, baking and pass generation.

Armature / Rig

Rigged subjects use Blender Actions and may export authored travel through root_delta according to the selected motion mode.

Mesh

A root Mesh can be baked without a rig. Its mesh descendants are part of the subject hierarchy.

Empty hierarchy

An Empty with mesh descendants can group a non-rigged actor without introducing a skeletal rig.

Collection

A Collection can be the authoring Subject. SpriteOrbit recursively gathers Mesh objects from nested child Collections and exports the existing OBJECT runtime contract.

Static Snapshot

OBJECT subjects may use an actionless one-frame state. SpriteOrbit does not invent root-motion data for them.

Animations

Build runtime states from Blender animation sources.

Actions

A rig state can reference an existing Blender Action and carry its own frame range, FPS, loop flag and motion mode.

FBX multi-select

Import selected FBX clips instead of having to ingest every file in a folder.

Split by Markers

A long Action/timeline can be divided into separate states using markers.

Loop / One Shot

Imported clips are evaluated for looping behavior so one-shots are less likely to ship as looping states by accident.

NLA isolation

During measurement and bake, SpriteOrbit isolates the chosen Action from the NLA stack and restores the artist state afterwards.

Motion

Choose where authored travel lives.

Pick the mode based on whether the runtime or the sprite pixels should carry movement.

Locked in Cell

Removes planar travel from the pixels and exports it in root_delta. Typical for looping Walk/Run when the game moves the actor.

Locked in Cell + Height

Also exports vertical travel. Useful for compact jump cells when the runtime will apply root_delta.z.

Travel in Pixels

Keeps authored movement inside the sheet. Useful for one-shot motion that should visibly cross the cell, accepting a larger frame.

Directions, Camera & Framing

Define how the actor is sampled.

  • Direction count: 1, 2, 4, 8 or 16 azimuth directions at one authored camera elevation.
  • Orthographic is the default and legacy fallback projection.
  • Perspective uses a fixed focal-length camera and exports the parameters required by the projection contract.
  • Preview Camera and the bake share the same projection/framing contract.
  • Measure Framing helps validate silhouette size before a long render.
  • Atlas-size warnings let you reduce FPS, frame range, direction count or cell resolution when needed.

Output Passes

Generate only the runtime data you need.

Lit Color + Ground Shadow

Lit Color is the main directional atlas. Ground Shadow can be delivered as a separate atlas or baked into the color output.

2D Normal + Material ID

View-space 2D normals for runtime lighting and material-group IDs for masking/effects.

Emissive + Roughness

Linear material-derived emission luminance and source roughness for supported/common shader setups.

AO + Depth

Actor-local ambient accessibility plus normalized linear view distance with near/far reconstruction values in metadata.

Bake What Changed

Rebuild stale output instead of blindly rendering everything.

SpriteOrbit tracks layered fingerprints for layout and individual passes. Bake What Changed evaluates which included states and passes are stale, missing or still current.

Existing output is reused only when its stored fingerprint and required layout/dimensions still match the current contract. A full bake remains available when you want to rebuild deliberately.

  • Layout-affecting changes invalidate dependent passes.
  • Pass-specific changes can invalidate one output without forcing unrelated passes stale.
  • State-level selection avoids rebuilding animation states that remain current.
  • Reuse validation checks more than file existence; incompatible output is rejected rather than silently merged.

SpriteOrbit Format v1

Start runtime integration from the unit manifest.

A bake writes _unit.json as the canonical actor entry point plus one _.json file for every baked state. FORMAT.md and the JSON schemas remain the formal technical source of truth.

The unit manifest summarizes states and pass filenames. Per-state metadata contains frame rectangles, camera fit and motion information used for detailed runtime playback.

  • Top-left pixel origin for rects and pivots.
  • Frame records carry explicit direction and frame indices.
  • Current manifests identify RIGGED versus OBJECT runtime subjects.
  • Projection, camera/framing, lighting, motion and optional pass references are represented explicitly.
  • Current bakes include pass-specific fingerprints used by selective rebake/reuse validation.

Compatibility & Integration

Current verified support state.

  • Blender requirement: 4.2 or newer.
  • Release smoke-tested: Blender 4.2.0, Blender 4.5.13 LTS and Blender 5.1.2.
  • Production bake path: Cycles.
  • Current v1 scope: directional azimuth sampling at one camera elevation, not a full spherical/hemisphere impostor system.
  • Unity: an integration package exists, but the full workflow is still in validation before a stronger public support claim.
  • Unreal Engine: the versioned format can be consumed by a custom loader, but a complete official importer/runtime is not currently advertised as finished.

Troubleshooting

First checks before treating a result as a bug.

Actor is cropped or framing looks wrong

Use Preview Camera and Measure Framing, then review cell size and framing margin before a full bake.

Atlas is too large

Review the atlas-size warning and reduce frame rate/range, direction count or cell resolution where the art direction allows it.

Wrong animation state

Confirm the state references the intended Action/frame range and review the loop/one-shot result for imported clips.

Unexpected pose influence

Current builds isolate the selected Action from NLA during measurement and bake. If unrelated NLA still changes output, capture a minimal file and report it.

Bake What Changed wants more work than expected

A layout-level change intentionally invalidates every pass that depends on that layout.

Engine integration question

Treat FORMAT.md and the schemas as the contract. Do not infer runtime behavior only from PNG file names.

Next

Product overview and usage documentation stay separate.

Back to SpriteOrbit

Return to the product page for the commercial overview, visual demos and release status.

SpriteOrbit product page