DOCSEARCHbyAlgolia
Submit Docs

Dreamlab Documentation

website·Indexed 32 days ago

https://docs.dreamlab.gg

An open-source web game engine featuring real-time collaboration and integrated Git-style version control. The documentation covers core systems including the AudioSource system, physics colliders, tilemaps, and UIBehavior. It provides guides on network authority, synced values via @syncedValue(), and the Key-Value (KV) API, along with building blocks for character controllers, health systems, and lighting effects.

Tokens
27K
Snippets
109
Records
166
Agent score
54%

What's inside Dreamlab

  1. Overview of Dreamlab 2D Game Engine

    Dreamlab is a browser-based 2D game engine designed for creating both singleplayer and online games. Key capabilities include:

    • Native Multiplayer: Games are multiplayer-ready by default without requiring manual server setup or external plug-ins.
    • Real-time Collaboration: Multiple users can edit code and game levels simultaneously.
    • AI Assistance: Includes built-in AI tools to assist developers in writing code.

  2. Understand Dreamlab physics entity simulation and visibility

    Physics entities are not rendered to the scene by default. To visualize them, enable the physics debug overlay in the editor to see wireframe representations of colliders and rigidbodies.

    Simulation is handled by a single client (or the server) at a time, with position and rotation synced to others. Entities in the world root are simulated on the server by default unless a client takes authority of the entity.

  3. Understand Dreamlab scene graph roots

    Dreamlab's scene graph is organized into four top-level roots that determine where an entity exists and which environment executes its Behaviors:

    • world: Shared across the server and all clients. Used for network-synced gameplay objects like terrain, NPCs, and pickups.
    • local: Exists only on each individual client. Used for UI, the active Camera, client-side VFX, and helper scripts.
    • server: Exists only on the server. Used for game-wide managers, match timers, and scoreboards.
    • prefabs: Editor-only templates (disabled at runtime). Used as blueprints to be cloned into other roots.

  4. Use real-time collaboration in Dreamlab

    Dreamlab provides Google Docs-style real-time collaboration, allowing game jam teams to collaborate on code and level design simultaneously. This feature is automatically available on all Dreamlab projects and requires no manual setup.

  5. Understand the Dreamlab game loop execution order

    Dreamlab simulates the game world at a fixed tick-rate (60 TPS by default). The engine follows a guaranteed execution order for behavior callbacks each tick: onPreTick → Physics/Engine Simulations → onTick → onPostTick → Network Snapshot. On the client, an optional onFrame hook runs for extra rendering per display frame. Note that while the phase order is guaranteed, Behaviors within the same phase execute in an undefined order.

  6. Manage persistent state with the Key-Value (KV) API

    Dreamlab games are stateless by default. To persist state between instances, use the Key-Value (KV) API.

    Scope and Permissions:

    • Project Scope: Data is scoped to the project; cross-project persistence is not possible.
    • Player Scope: Data is scoped per-player. Clients can only read/write their own scope.
    • Server Scope: The server has its own scope and can read/write to any player's scope.

    Technical Constraints:

    • Keys must be of type string.
    • Values must be JSON serializable.

  7. Implement game logic using the Behavior class

    In @dreamlab/engine, a Behavior is a modular piece of logic attached to an entity to encapsulate functionality like movement, AI, or health management. Behaviors utilize lifecycle methods for timing and can define synchronized values for network state or inspector GUI visibility.
    import { Behavior } from "@dreamlab/engine";

export default class MyBehavior extends Behavior {
  onInitialize(): void {
    // Setup tasks
  }

  onTick(): void {
    // Logic updated every game tick
  }
}

  8. Use the Vector2 class for 2D vector operations

    The Vector2 class in @dreamlab/engine provides a comprehensive set of tools for 2D vector mathematics. It works with the IVector2 interface, which is a simple object containing x and y number properties. The class supports both static methods for functional-style operations and instance methods for chainable operations.
    import { Vector2, IVector2 } from "@dreamlab/engine";

// Using the interface
const v: IVector2 = { x: 0, y: 0 };

// Creating a Vector2 instance
const myVector: Vector2 = new Vector2(v);

  9. Access child entities within a Behavior

    Access child entities directly using the _ property on the entity. Avoid using this.entity.children.find() as it is inefficient.

    • Direct access: this.entity._.ChildName
    • Names with spaces: this.entity._["My Entity"]
    • Chained access: this.entity.myChild.myOtherChild

  10. Use the Pop-out Script Editor for better performance

    You can open the editor in a separate window using the 'Pop Out Script Editor' button in the top-right. For optimal performance when using the pop-out window, disable the 'Same-Window Script Editor' option in the settings menu.

  11. Collaborate on a project in real-time

    File operations (creating, renaming, deleting, and editing) are broadcast to other users in the same project in near real-time. If synchronization issues occur, try closing file tabs and reloading the page. If the problem persists, reset collaborator sync via the settings menu in the top-right.

  12. Inspect KV data using the KV Debugger component

    To debug the KV data stored in your project, attach the kv-debugger.tsx behavior script to a UILayer located in the world root. This allows developers to view and edit project-scoped data directly within the game environment.