just_game_engine_formats library

The Just Game Engine's saved file formats, in pure Dart.

Everything here reads and writes plain JSON maps — no Flutter, no dart:ui, no dart:io — so the engine, the editor and the just command-line tool all migrate and check files with the same code:

just_game_engine re-exports all of it, so a game imports the engine as before.

Classes

AnimatorBlendMotion
One clip of a blend tree, and where it sits.
AnimatorBlendTree
A state that plays several clips at once, weighted by parameters: walk to run by speed (1-D), or strafing in eight directions (2-D). A target that can't blend (a sprite) plays the heaviest motion.
AnimatorCondition
One test a transition makes: speed > 10, grounded == true. For a trigger the op and value are ignored — it holds while the trigger is set.
AnimatorGraph
A whole state machine. Immutable: an editor replaces it.
AnimatorParameter
A named value transitions are conditioned on.
AnimatorState
A state: one clip, playing.
AnimatorTransition
A way from one state to another, taken when every condition holds.
LayerEntry
One layer in assets/project/physics.json.
Material2DEffect
A switch in a 2-D material: off unless the file turns it on.
Material2DEffects
Every effect a 2-D material can switch on, in the order a material applies them (and a file saves them).
Material2DFile
A 2-D material saved in its own file (*.material2d.json): effects for sprites, shapes and tile layers (Material2DKind.sprite), or for the whole frame from a camera (Material2DKind.screen).
Material2DParam
One value of a Material2DEffect.
MaterialChain
Walks a variant's parents and lays each file over the one before.
MaterialFile
A material saved in its own file (*.material.json), which 3-D shapes and models refer to by path: change it once and everything drawn with it changes.
MigrationHooks
The rules a package adds to the scene and timeline migrations, on top of the engine's own — its old component shapes brought forward.
MigrationNote
Something one migration step noticed that a person may want to know.
MigrationResult
A scene brought up to the current format, and what was found on the way.
MigrationRun
One migration in progress: the hooks it runs with and what it finds. Handed to every step, so two migrations never share what they found.
PhysicsLayersFile
assets/project/physics.json: the named physics layers and which of them collide, as the engine's PhysicsLayers reads it — {version, layers: [{index, name?, color?, description?, ignores?}]}.
PrefabApply
Writes what an instance changes into its prefab, so that every instance has it: an editor's Apply.
PrefabCollapse
Works out what an instance changes, from its entities as they are now against what its prefab makes on its own: what an editor saves.
PrefabEntity
One entity of a PrefabFile.
PrefabExpander
Turns prefab instances into the entities they make: the prefab's own, each nested instance in it made in turn, and the instance's changes applied. Plain JSON in, plain JSON out — the engine, the editor and the command line expand the same way.
PrefabFile
A prefab saved in its own file (*.prefab.json): entities — one at the top, the rest under it — that scenes and other prefabs place as an instance, changing what they need to (PrefabInstance).
PrefabInstance
An instance of a prefab — in a scene, or in another prefab — and what it changes: fields (overrides), names and switches of the entities in it, entities removed, components added and removed. Everything else is the prefab's, so an edit to the prefab reaches every instance.
PrefabNode
One entity a prefab instance makes: where it is in the prefab (path, a path of ids), its name and switch, the entity it is under (parent, a path too; null at the top) and its components as saved — copies, to change freely.
PrefabOverride
One field of a component changed in an instance: on the entity at target (a path of ids, c3/x9 for x9 inside the instance c3), component's field is value (as saved).
ResolvedMaterial<T>
A material file with every parent laid under it, and what went wrong on the way.
SceneFormat
The saved scene format's version, and how older files are brought up to date.
SceneManifest
assets/scenes/scenes.json: the scenes the game plays, in order.
SceneMigration
One step of the scene-format migration chain: from version from to from + 1.
SceneMigrations
Every migration, in order.
SceneNames
The rules for a scene's name: a Dart identifier that is not a keyword, unique ignoring case.
SceneStarters
The scene a new level starts from, as its file holds it.
TagEntry
One tag in assets/project/tags.json.
TagsFile
assets/project/tags.json: the project's tags, as the engine's TagLibrary reads it — {version, tags: [...]}, or the oldest form, a bare list; a tag as {name, color?, description?} or a bare name.
TimelineFormat
The timeline file format: its current version, and bringing an older file up to it.
TimelineMigration
One step of the timeline-format migration chain: from version from to from + 1.
TimelineV1ToV2
v1 → v2: rotation became three angles.
V0ToV1
v0 → v1: every component becomes {type, fields}.
V1ToV2
v1 → v2: the camera becomes virtual cameras.
V2ToV3
v2 → v3: sprites play from an atlas.
V3ToV4
v3 → v4: timelines.
V4ToV5
v4 → v5: UI that keeps its look.
V5ToV6
v5 → v6: every entity is 3-D.
V6ToV7
v6 → v7: tags and targets.
V7ToV8
v7 → v8: physics bodies.
V8ToV9
v8 → v9: one physics model for 2-D and 3-D.
V9ToV10
v9 → v10: a scene entry may be an instance of a prefab file — a prefab block (path, and what it changes) in place of components — and an entry may name an entity inside such an instance as its parent (parentTarget, a path of the prefab's ids, beside parentName).

Enums

AnimatorBlendType
How a blend tree places its motions.
AnimatorOp
How a condition compares its parameter with its value.
AnimatorParameterType
What kind of value a parameter holds.
Material2DKind
What a 2-D material is put on.
Material2DValue
What kind of value a Material2DParam holds, and how a file saves it.
MaterialAlpha
How a MaterialFile treats what is behind it.
MaterialKind
What a MaterialFile is.
MaterialUv
How a MaterialFile's maps are laid over a surface.

Typedefs

ComponentMigration = Map<String, dynamic> Function(Map<String, dynamic> component)
Rewrites one component's v0 JSON to its v1 shape. Receives the component map with type already read; must return {type, fields}.
EntityMigration = void Function(Map<String, dynamic> entity, Map<String, dynamic> scene)
Rewrites one entity in place. scene is the whole file, for a migration that has to look at — or add — other entities.
FieldMigration = void Function(Map<String, dynamic> fields)
Rewrites a component's fields map in place.
TrackMigration = Map<String, dynamic>? Function(Map<String, dynamic> track)
Rewrites one track of a version-1 timeline for version 2. Returns the track, changed or not, or null to drop it.

Exceptions / Errors

UnsupportedFormatVersionException
A saved file declares a format version newer than this engine reads.