TRUEWAY
Menu
EN only

SpriteOrbit Documentation

Install. Preview. Export.

Follow the illustrated Quick Start, then open the reference only when you need more detail. The Mutant export was checked with SpriteOrbit 1.0.0 on Blender 5.2.1 LTS. Use your own character to follow the same workflow.

Start the first exportBack to SpriteOrbit

Quick Start · SpriteOrbit 1.0.0

Your character. Your first sprite atlas.

Follow these steps with your own animated model. The Mutant shown here was exported with the 1.0.0 release on Blender 5.2.1 LTS: Walk, four views, 12 FPS and 256×256 cells. The character is a demonstration asset, not part of the product download.

  1. 01Install SpriteOrbit

    In Blender, open Edit → Preferences → Get Extensions. Use the menu at the top right → Install from Disk and select SpriteOrbit-1.0.0.zip. Enable SpriteOrbit if requested.

    In the 3D View, press N to open the sidebar and choose the SpriteOrbit tab.

  2. 02Choose your character and output folder

    Open your animated character file. In Actor, set Subject to its armature and choose an Export Name. Our example uses the MutantColors rig and SpriteOrbitMutant as the export name.

    Choose a writable, empty Output folder. Keep textures available or packed in your source file. Subject names depend on your own model.

    Actor panel controls for selecting a Subject, Export Name and Output folder
    Actor controls in version 1.0.0. Choose your own Subject and Export Name; the names in this panel illustration are examples.

  3. 03Choose the animation

    In Animations, add your walking Action or import the FBX animation. Name the state walk and enable Include in Bake only for that state.

    Keep Use Full Action Range enabled and Loop on. Set Sprite Output → FPS to 12. Use Locked in Cell when gameplay will control movement. Our source action produces 17 exported frames per view; your action length determines your own frame count.

  4. 04Frame the character

    In Look → Camera & Framing, choose Orthographic, 4 Directions, 256×256 Frame Resolution and 1× Supersampling. Set the azimuth and tilt for the view your game needs.

    Use Preview Camera and Measure Framing to check the whole silhouette. For this first export, enable only Lit Color. Choose Cycles with 16 samples; additional passes can be added later.

    Actual Mutant sprite from the same 3D source used for the animation example
    Keep the whole character inside the camera frame, including its claws and feet.

  5. 05Bake and preview

    In Bake, choose Bake What Changed. On the first run, it writes the missing files for your included animation.

    When it finishes, open Review, select walk and use Show Preview. Check the different Direction values. The preview below plays the actual exported Mutant atlas.

    View 1/4
    View 2/4
    View 3/4
    View 4/4
    12 FPS · 256×256 px · Open the Mutant atlas

  6. 06Open the exported files

    Open Output using the folder icon in Actor. A color-only export produces the atlas, state JSON and unit JSON. Their names use your Export Name and animation state.

    In our worked example the atlas is 4352×1024: 17 frames in each of four rows. Start integration from SpriteOrbitMutant_unit.json and keep the other files beside it. Engine playback is a separate integration step.

    Actual Mutant Walk atlas: four directions and 17 frames in each row
    Open the full-size Mutant atlas to inspect individual frames.

Reference

Open a topic below. Existing section links remain available.

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.

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.

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.

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.

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.

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.

Start runtime integration from the unit manifest.

A bake writes <Unit>_unit.json as the canonical actor entry point plus one <Unit>_<state>.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.

Current verified support state.

  • Blender requirement: 4.2 or newer.
  • Final 1.0.0 artifact lifecycle-tested on Blender 5.2.1 LTS; earlier compatibility coverage also includes 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: the optional package was release-validated on Unity 6000.3.24f1 / Windows D3D12 (110/110 EditMode, 33/33 PlayMode plus standalone GPU smoke). It declares Unity 2021.3 as its minimum, but the full release QA matrix was not rerun on 2021.3.
  • Unreal Engine: the versioned format can be consumed by a custom loader, but a complete official importer/runtime is not currently advertised as finished.

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.

Optional Unity package and runtime benchmark

The optional Unity package was release-validated on Unity 6000.3.24f1 / Windows D3D12 with 110/110 EditMode and 33/33 PlayMode tests plus a standalone GPU smoke. It declares Unity 2021.3 as its minimum; that version did not receive the full release QA matrix.

The million-unit demonstration comes from a newer development branch, separate from the validated 1.0.0 package. Recorded configuration: GTX 1050 Ti, Unity 6000.3.24f1, Windows D3D12, 1920×1080, 1,000,000 submitted units, 109.9 FPS average, 8.229 ms GPU. These results apply to that scene and hardware.

Recorded million-unit SpriteOrbit runtime demonstration in Unity
Separate development benchmark. Conditions are listed above.

Need help with the first export?

SpriteOrbit support

Include the Blender version, SpriteOrbit build and the numbered step that failed.

Contact Trueway