Getting started

Introduction

What Just Game Engine is, the tools that come with it, the platforms it runs on and where the 2.0 release stands.

Just Game Engine is a game engine for Flutter. It is 2D, with 3D graphics and 3D physics you can opt into. A game is entities, components and systems (ECS) in a World, and its levels are JSON scenes that the game loads at run time. The engine draws inside an ordinary Flutter widget, GameWidget, so a game can be a whole app or one screen of a larger one.

It brings level maps, sprites and animator graphs, timelines, virtual cameras, physics, particles, audio and action-based input. The level editor saves the same scene files the game loads, so nothing stands between saving a level and shipping it.

A first look

This is a whole game: a floor, and a ball that falls onto it.

lib/main.dart
import 'package:flutter/material.dart';
import 'package:just_game_engine/just_game_engine.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // The engine, with its standard systems.
  final engine = Engine(
    config: const EngineConfig(defaultSystems: DefaultSystems.all),
  );
  await engine.initialize();

  // y points down, and (0, 0) is the middle of the screen until a
  // virtual camera takes over.
  engine.world
    ..createEntityWithComponents([
      TransformComponent(position: Vector3(0, 200, 0)),
      Rectangle2DComponent(width: 600, height: 24),
      // A collider alone is a static body; this one is the drawn rectangle.
      Collider2DComponent(shape: Collider2DShape.matchShape),
    ], name: 'Floor')
    ..createEntityWithComponents([
      TransformComponent(position: Vector3(0, -150, 0)),
      Circle2DComponent(radius: 24),
      RigidBody2DComponent(),
      Collider2DComponent(shape: Collider2DShape.matchShape),
    ], name: 'Ball');

  engine.start();
  runApp(MaterialApp(home: GameWidget(engine: engine)));
}
  • Engine() makes a new engine each time. initialize() builds its subsystems and world; finish it before you use the engine.
  • engine.start() starts the game loop. GameWidget runs it on Flutter's frame ticker, draws the world, and passes keys and pointers to engine.input.
  • When you are done, await engine.dispose(). Disposal is final: to start over, make a new Engine().

Your first game builds on this step by step.

The toolkit

The engine is one package. These are the others you will meet:

PackageWhat it isVersion
just_game_engineThe engine: the ECS world, scenes, rendering, physics, audio, input and the rest.2.0.0
just_game_engine_editorA level editor that runs inside your game in a desktop debug build. See Level editor.0.1.0, made for engine 2.0.x
just_core_clijust, the command-line tool: it creates projects, checks their setup and upgrades them.0.2.x
just_game_engine_cliThe just game commands: run, build, scenes, release checks and migrations. See The just CLI.0.2.x
just_game_engine_formatsThe saved file formats (scenes, timelines, animator graphs) and their migrations, in pure Dart. The engine re-exports it, and the editor and the CLI migrate files with the same code.comes with the engine
just_game_servicesAchievements, sign-in, leaderboards, currency, inventory and ads, as opt-in engine services. See Game services.0.1.0, not yet on pub.dev

Under the engine sit packages of the same family: just_physics_engine (Box2D v3 through FFI where its native library loads, a pure-Dart engine with the same API elsewhere, and Jolt Physics for 3D), just_graphics_engine (3D on Flutter GPU), just_inputs, just_audio_engine, just_tiled and a few smaller ones. You rarely import them yourself.

Platforms

  • The engine is built for Android, iOS, Windows, macOS, Linux and the web, compiled to JavaScript or WebAssembly. It is verified on Windows, Android (Vulkan) and the web. Linux, iOS and macOS are untested: they are expected to build, but have never been run.
  • 3D graphics draw where Flutter GPU does: not on the web, and not on Android devices without Vulkan. There the game still runs, and the 3D view shows a short note.
  • 3D physics runs where Jolt is built, which is everywhere but the web.
  • On the web, 2D physics runs on the pure-Dart engine, audio starts at the first key or pointer press, and fragment-shader effects are skipped.
  • The editor edits on Windows, macOS and Linux, in a debug build. On other platforms, and in any profile or release build, the game runs on its own.
  • The just tool runs on Windows, macOS and Linux.

Platforms has the details for each one.

What's included

Version status

2.0.0 is the latest stable release, and these docs are written for it. 2.0 is a breaking release: it came out first as dev releases (2.0.0-dev.1 to dev.3), and the last 1.x release is 1.6.1.

  • Coming from 1.x? Read Migrating from 1.x. Scene files saved by earlier versions still load: they are migrated in memory as they are read.
  • Coming from a 2.0 dev release? Change the constraint to ^2.0.0, and read the CHANGELOG entries after yours.
  • The examples site at examples.engine.justunknown.com shows the engine feature by feature, written for 2.0.
  • The editor and the CLI are young: the editor is at 0.1, the CLI at 0.2. Use the editor release made for this engine; just game keeps the engine's packages on versions that work together.

License

The engine, the editor and the CLI packages are open source under the BSD 3-Clause license. Each repository has its LICENSE file.

Getting help

  • Discord: ask questions and share what you build at discord.gg/VXFxVj4Y.
  • Issues: report bugs against the engine, the editor or the CLI.
  • API reference: every public class and member is on pub.dev.
  • The repository's own docs: the engine on GitHub has its README, QUICKSTART, MIGRATION, ARCHITECTURE and an API map by area.
This page as Markdown