just_game_engine_formats 0.2.0

The Just Game Engine's saved file formats in pure Dart: scenes and timelines with their migrations, animator graphs, tags and physics layers.

0.2.0

• Scene format 10 (V9ToV10, a step that changes nothing): a scene entry may place a prefab.
• Prefab files: PrefabFile (*.prefab.json, format 1: one entity at the top, ids of letters and digits, parents before children), PrefabEntity, PrefabInstance (overrides, removed entities, added and removed components, names), PrefabOverride; PrefabExpander (expand, apply, expandScene, collapseScene, pathsIn), PrefabCollapse.diff and PrefabApply for an editor's round trip.
• Material files: MaterialFile (*.material.json, format 1): lit or layered, colours, five maps, tiling, natural, metre or world texture coordinates, up to four layers; transparency (MaterialAlpha: opaque, cutout with alphaCutoff, or blend, where opacity counts), occlusion strength, and the maps moved (offset) and turned (rotation).
• 2-D material files: Material2DFile (*.material2d.json, format 1) for sprites, shapes and tile layers, or the whole frame (Material2DKind.screen). Effects are switches with values (Material2DEffects: wave, scroll, palette swap, gradient map, greyscale, tint, flash, normal map, emissive, dissolve, shine, outline, glow, drop shadow, and for the screen pixelate, CRT, colour grade, scanlines, vignette), each value found by key (flash.amount), typed and ranged (Material2DParam, animatable for those the game may change as it runs). A normal map is read green up (OpenGL) unless normalMap.directX says green down. It is read strictly: an effect or value it does not know is a FormatException.
• Material variants: a 3-D or 2-D material may name a parent and keep only what it changes (overrides; a 2-D variant may also turn a parent's effect off). MaterialChain.resolve3D and resolve2D lay each file over its parents and say when one is missing or they loop; resolve, withEdit (given what was shown, a value set equal to the file's own default still counts as the variant's), withoutOverride, withValue and withoutEffectOverride are what an editor needs.

0.1.0

The first release: the Just Game Engine's saved file formats as a pure Dart package, with no Flutter, dart:ui or dart:io. The engine, the editor and the just command-line tool all read and migrate files with it, and just_game_engine re-exports all of it.

• Scenes: SceneFormat (format 9) brings a *.scene.json from any older format up to date in memory. SceneMigrations.chain holds the steps V0ToV1 to V8ToV9, and SceneFormat.migrateWithReport says what changed: MigrationNotes, and the entities whose sprite sheet needs exporting as an atlas. Packages bring their own components forward through MigrationHooks.
• Timelines: TimelineFormat (format 2) for *.timeline.json files and the timelines a scene keeps inline.
• Animator graphs: AnimatorGraph reads and writes *.animator.json: states, transitions, conditions and parameters, plus crossfades and 1-D and 2-D blend trees (format 2). A graph is written as format 1 unless it uses either. validate() lists everything wrong with a graph.
• New scenes and the scene list: SceneStarters (the 2-D and 3-D scenes a new level starts from), SceneManifest (scenes.json) and SceneNames (the naming rules).
• Project files: TagsFile and PhysicsLayersFile read assets/project/tags.json and assets/project/physics.json as the engine does.
• Errors: a file newer than this package reads throws UnsupportedFormatVersionException. A broken one throws a FormatException naming the file or the migration step: a version that is not a whole number, or a value of the wrong type. UnsupportedFormatVersionException is a FormatException too, so one on FormatException catches both.
• Migrated scenes and timelines, and the starter scenes, are typed as jsonDecode types a file, so they can be edited in place.