Tools

Level editor

Install the level editor, give it an entry point that never ships, register your components, and find your way around its tools.

The Just Game Engine editor is a level editor that runs inside your game while you develop it. You start the game's editor entry point in a debug build on Windows, macOS or Linux, and the running game is the scene you edit. 2D and 3D scenes, the Level Map, physics, cameras, timelines, materials and play-testing share one undo stack, and a profile or release build of the game holds none of it. The editor overview has screenshots and the feature list.

Install

The editor is a dev dependency: only your editor entry point imports it, so it never ships, and a release build also leaves out the native plugins only the editor brings. Add it from the project folder with flutter pub add --dev just_game_engine_editor, which puts it under dev_dependencies. Each editor release is made for one engine release: use the one made for just_game_engine 2.0.0, with Flutter 3.47 (3.47.1 or newer; see "Flutter versions" in Installation). In a project made with just, the editor says when it runs on another Flutter than the one the project pins, and how to fix it.

The editor entry point

Keep lib/main.dart free of the editor, and give the editor an entry point of its own, lib/main_editor.dart:

lib/main_editor.dart
// The editor is a dev dependency, imported by this entry point alone.
// ignore_for_file: depend_on_referenced_packages

import 'package:flutter/foundation.dart' show kDebugMode;
import 'package:flutter/material.dart';
import 'package:just_game_engine/just_game_engine.dart';
import 'package:just_game_engine_editor/just_game_engine_editor.dart';

import 'main.dart' show MyGame; // the game, as lib/main.dart runs it

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  // kDebugMode is a compile-time constant: a profile or release build keeps
  // only the else branch, so it holds no editor.
  if (kDebugMode) {
    await _runEditor();
  } else {
    runApp(const MyGame());
  }
}

Future<void> _runEditor() async {
  final engine = Engine(
    config: const EngineConfig(
      extensions: [MyGameExtension()], // your components (below)
      defaultSystems: DefaultSystems.all,
    ),
  );
  await engine.initialize(); // boot the game's world here, as main.dart does
  final plugin = await JustGameEditorPlugin.register(
    engine: engine,
    modules: [MyGameModule()], // what your game adds to the editor
    spawners: mySpawners, // what Play spawns at each spawn point
    onReassemble: (plugin) => rewire(engine, plugin),
  );
  engine.start();
  runApp(
    MaterialApp(
      home: JustGameEngineEditor(engine: engine, plugin: plugin),
    ),
  );
}

/// Runs after every hot reload: what main handed the editor from code.
void rewire(Engine engine, JustGameEditorPlugin plugin) {
  plugin.syncModules([MyGameModule()]); // a module added since launch joins
  plugin.scope.spawners.value = mySpawners; // read at the next Play
}
  • Why if (kDebugMode). Because kDebugMode is a constant, the compiler keeps one branch and drops the other, so a release build of this file is the game alone. An early if (!kDebugMode) { ...; return; } is not the same: code after a return is still compiled in. just doctor checks that main keeps this shape.
  • JustGameEditorPlugin.register returns null in a profile or release build, and where the editor cannot run (JustGameEditorPlugin.supportsPlatform). JustGameEngineEditor is then a plain GameWidget.
  • The ignore_for_file line is there because flutter_lints reports a lib/ import of a package that is only a dev dependency.
  • Spawners are the game's own Spawner list. Play spawns through them, so the editor makes exactly the player the shipped game does.

Run it

Run flutter run -t lib/main_editor.dart -d windows (or macos, linux), or just game run --editor in a project made with just create. Start it from the project folder: the editor reads and saves the project's own files, relative to the working directory.

Hot reload

The editor runs in a debug build, so hot reload (r) and hot restart (R) work on it. A hot reload swaps the code but runs nothing again: not main, not a constructor. So after each reload the editor calls your onReassemble, where you hand over again what main did once (modules, spawners, systems added since launch). It then puts the component definitions in place again, including each RefreshableExtension's, so a field you added shows in the inspector and is saved; rebuilds its docks, commands, prefabs and inspector sections from the modules; and brings live components up to a definition that changed.

Write what is built from code as a getter, not a static final, which is built once and kept: component definitions, prefabs, workspaces. Some changes still need a hot restart: a changed argument of a module or system that is already running, and the engine's configuration.

Register your components

A component is described once, in the game, by a ComponentDefinition. That one description saves it, loads it in the shipped game, and builds its inspector section:

lib/game/health.dart
import 'package:flutter/material.dart' show Icons;
import 'package:just_game_engine/just_game_engine.dart';

class MyHealthComponent extends Component {
  int maxHp = 3;
}

// A getter, so a hot reload builds it again from the code.
ComponentDefinition<MyHealthComponent> get myHealthDefinition =>
    ComponentDefinition(
      type: 'MyHealthComponent',
      create: MyHealthComponent.new,
      fields: [
        FieldDefinition(
          name: 'maxHp',
          kind: FieldTypes.integer,
          min: 0,
          read: (c) => (c as MyHealthComponent).maxHp,
          write: (c, v) => (c as MyHealthComponent).maxHp = v as int,
        ),
      ],
      // What the inspector shows. The game ignores it.
      hints: const ComponentHints(
        name: 'Health',
        group: 'Gameplay',
        icon: Icons.favorite,
        fields: {
          'maxHp': FieldHint(label: 'Max HP', scrub: ScrubHint(integer: true)),
        },
      ),
    );

// Registers the game's components on the engine it is given, and again,
// as the code now makes them, after a hot reload.
class MyGameExtension implements RefreshableExtension {
  const MyGameExtension();

  @override
  String get id => 'my_game';

  @override
  void install(EngineContext context) =>
      context.definitions.register(myHealthDefinition);

  @override
  void refresh(EngineContext context) =>
      context.definitions.refresh([myHealthDefinition]);
}

Give the extension to every engine the game makes, in lib/main.dart as well as in the editor entry point: EngineConfig(extensions: [MyGameExtension()]). A component with no registered definition is not shown, and is left out of the save with a warning in the log, because the shipped game could not load it. The engine has a HealthComponent of its own, so a game's component needs a type name of its own.

Add an editor module

An EditorModule is where the editor's side of your game goes: prefabs, viewport tools, overlays, icons, checks and inspector editors for field types of your own. It lives in the editor entry point, or in a file only it imports, never in lib/main.dart's imports:

lib/editor/my_game_module.dart
import 'package:flutter/material.dart';
import 'package:just_game_engine/just_game_engine.dart';
import 'package:just_game_engine_editor/just_game_engine_editor.dart';

import '../game/health.dart';

class MyGameModule extends EditorModule {
  @override
  String get id => 'my_game';

  @override
  String get name => 'My Game';

  // In every Level Designer, beside the editor's own shapes.
  @override
  List<PrefabDefinition> get sharedPrefabs => [
    PrefabDefinition(
      id: 'my_game.enemy',
      name: 'Enemy',
      category: 'Enemies',
      icon: Icons.bug_report,
      color: const Color(0xFFE57373),
      placement: PrefabPlacement.point,
      defaultSize: const Size(32, 32),
      build: (position, size) => [
        TransformComponent(position: Vector3(position.dx, position.dy, 0)),
        Rectangle2DComponent(width: size.width, height: size.height),
        MyHealthComponent(),
      ],
    ),
  ];
}
  • Prefabs in sharedPrefabs appear in every Level Designer. Prefabs in prefabs make the module a Level Designer of its own, picked in the designer switch.
  • More contributions: scene-tree icons (entityIcons), docks, toolbar buttons, settings pages, commands and key bindings, checks for the Problems dock, kinds of file for the Assets dock, and the tags its code relies on.
  • Lifecycle: onRegister runs once and onReassemble after each hot reload. Everything a module contributes is rebuilt from it on every reload, so nothing piles up.
  • Built-ins: the editor's own tools arrive the same way, as BuiltInEditorModule, BuiltInMaterialsModule, BuiltInAssetStoreModule (the Asset Store, for plugins, kits and assets) and, for a game with 3D graphics, BuiltInGraphics3DModule. Kits and plugins build their modules on just_editor_core, which this package re-exports.

Open the editor

Press F1 at run time to show or hide the editor. The game viewport shifts left, and the right panel shows the scene tree, the inspector and the Scenes list.

With no scene open, the viewport shows a start card: New scene, Reopen the last scene, the steps to a saved level, and the tools that need no scene. New scene asks for a name and whether the scene is 2D or 3D, and writes the same starter scene as just game scene new: a camera and the player's spawn point, plus, in 2D, the bounds the camera keeps to. The Scenes list searches, sorts and reorders: dragging a scene, or Alt+Up/Down, sets the play order in scenes.json, and the first scene is where the game starts.

A tour of the tools

  • Scenes and saving. A scene is one file, assets/scenes/<name>.scene.json, and the game loads the same file through SceneLoader. Ctrl+S saves it and any map files it uses; saving during a play-test saves the level as authored, not as the game left it. Autosave runs every 2 minutes by default and keeps backups in .editor_backups/<scene>/; when a backup holds changes the file lacks, opening the scene offers to recover them. Older scene formats are migrated as they open, and the file changes only when you save.
  • Level Designer. F3, or the map icon on the play toolbar, opens it. Its tool strip has Draw (B), Paint (P), Sample (I), Stamp (S), Fill (G), Terrain (T), Erase (D), Select tiles (V) and Measure (M). A scene has one Level Map: tiles on square, isometric, staggered and hexagonal grids, with a built-in Basic shapes tileset (blocks, slopes, a one-way plank and more, each colliding as drawn) to block out a level before there is art. Everything you place becomes an entity on one of the map's layers, and Tiled maps import and export. A 3D scene gets a 3D Level Designer with its own Default 3D kit.
  • Inspector. It is built from each component's ComponentDefinition, with an editor for every field type, a colour picker, and tag and entity pickers. Physics bodies get one card for 2D and 3D alike: body type, material presets, Fit to visual, collider handles in the viewport, and collision layers picked by name and saved to assets/project/physics.json.
  • Play-testing. F5 plays in place, F6 pauses, F10 steps one frame and Shift+F5 restarts, with speeds from a quarter to double. Play spawns at every spawn point through your spawners, the game's camera brain drives the view, and Stop puts every authored entity back exactly as it was. F4 shows what the game camera frames while you work.
  • Timeline. The Timeline dock edits timelines that animate any component field, with a dope sheet, a curve editor, record mode and motion paths drawn in the viewport. See Timelines.
  • Materials. 3D materials (*.material.json) and 2D materials (*.material2d.json) are pictured in the Assets dock, edited in a Material window with a live preview, presets and variants, and dropped on what they draw. The 3D previews need Flutter GPU switched on in the game's runner (Installation); the 2D ones need nothing.
  • Docks. One tabbed panel at the foot of the editor, opened and shut with F2: Console (Ctrl+Shift+C), Assets (Ctrl+Shift+A), Timeline (Ctrl+Shift+T), Profiler (Ctrl+Shift+P), World (Ctrl+Shift+W), Search (Ctrl+Shift+F), History (Ctrl+Shift+H), Problems (Ctrl+Shift+E), Tags, Physics Layers and Animator. Problems lists what is wrong with the open scene, many items with a one-click fix. Tabs reorder and pop out, and the layout is remembered.

Key shortcuts

These are the defaults; change any of them in Settings (Ctrl+,) under Keyboard. On macOS, read Cmd wherever this page says Ctrl.

KeyAction
F1Show or hide the editor
F2Open or shut the dock panel
F3Open or close the Level Designer
F4The game camera preview
F5 / Shift+F5Play or stop / restart
F6, F10Pause or resume, step one frame
Ctrl+SSave the scene
Ctrl+Z / Ctrl+Shift+Z or Ctrl+YUndo / redo
Ctrl+C, Ctrl+V, Ctrl+D, DeleteCopy, paste, duplicate, delete
Q, W, E, RAll, Move, Scale, Rotate
F / Shift+FFrame the selection / everything
Ctrl+Shift+GThe Asset Store window

Platforms

  • The package compiles everywhere Flutter does, so a game that imports it in its editor entry point still builds for Android, iOS and the web.
  • Editing runs on a desktop (Windows, macOS or Linux), in a debug build launched from the project folder. On a phone, a tablet or the web the app has only its bundled, read-only assets, so register returns null and the game runs on its own.
  • macOS: a sandboxed debug app cannot write the project folder. Set com.apple.security.app-sandbox to false in macos/Runner/DebugProfile.entitlements; the release entitlements stay as they are. The Asset Store window also needs com.apple.security.network.client there, which just create adds and just doctor checks. Cmd is the primary modifier, and Backspace deletes as Delete does.

Asset Store, plugins and kits

A module reaches other projects inside a package. There are two kinds:

KindWhat it bringsIn the game's pubspec
PluginTools for the editor only, such as a window, a dock or an asset editor. Nothing of it ships.dev_dependencies
KitGame code and its editor half: components and systems the game runs, plus the prefabs, tools and inspector fields to place them.dependencies
  • From the Asset Store. Ctrl+Shift+G opens the store window, to browse, install, update and remove items. In a terminal, just add <id>, just remove <id> and just store list do the same. The store adds the package to pubspec.yaml and rewrites lib/editor/store_modules.g.dart (the editor modules) and lib/game/store_extensions.g.dart (the kits' engine extensions), which a project made with just create already uses. Hot restart (R) the editor after installing code.
  • By hand. Add the package to pubspec.yaml, add its module to modules in lib/main_editor.dart, and for a kit, give its engine extension to every engine the game makes, in lib/main.dart too. Import a package's editor library from lib/main_editor.dart only.

First-party modules include PlatformerModule (just_platformer_kit), ThirdPersonModule (just_third_person_kit), WorldBuilderModule (just_world_builder_kit), SpriteStudioModule (just_sprite_editor) and InputEditorModule (just_input_editor). The editor's README explains how to make and publish a plugin or kit of your own.

This page as Markdown