Skip to content

Commit a78c807

Browse files
CodedRedGITCodedRedGIT
committed
update entities page
1 parent 24b2a97 commit a78c807

2 files changed

Lines changed: 134 additions & 59 deletions

File tree

‎docs/guide/entities.mdx‎

Lines changed: 125 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,151 @@
11
---
22
sidebar_position: 2
3+
title: Entities
34
---
45

56
# Entities
67

7-
Entities are the building blocks of games. They are similar to Unity's `GameObject` or Godot's `Node`. They implement
8-
basic functionality, support nesting and hierarchy, and can be scripted using Behavior classes.
8+
Entities are Dreamlab's fundamental game objects—similar to Unity **GameObjects** or Godot **Nodes**.
9+
They
910

10-
Entities can be spawned using the right-click menu in the Scene Graph:
11-
![spawning entity menu](../../static/img/image-2.png)
11+
* own a **Transform** (position / rotation / scale / z-layer)
12+
* can nest to form a hierarchy
13+
* gain behavior through attached **Behavior** scripts
14+
* sync automatically when placed under the shared **`world`** root
1215

13-
## Entity Catalog
16+
Entities are usually added from the editor's right-click menu:
1417

15-
:::note
18+
![Spawn entity menu](../../static/img/image-2.png)
19+
20+
---
21+
22+
## 1. Quick start - spawning by script
23+
24+
### Create a brand-new entity
25+
26+
```ts
27+
// Spawn an Empty into the shared world root
28+
const pivot = game.world.spawn({
29+
name: "Pivot",
30+
type: Empty,
31+
transform: { position: { x: 4, y: 1 } },
32+
});
33+
```
34+
35+
### Clone a prefab at runtime
36+
37+
```ts
38+
// “Crate” lives under prefabs/
39+
// cloneInto returns the new instance
40+
const crate = game.prefabs._.Crate.cloneInto(game.world, {
41+
name: "Crate." + crypto.randomUUID(),
42+
authority: game.network.self, // I control this crate
43+
});
44+
crate.pos.set(2, 0);
45+
```
46+
47+
> `cloneInto()` duplicates the entity (plus all children & behaviors) and registers it in the target root.
48+
49+
---
50+
51+
## 2. Core concepts
52+
53+
| Feature | What / Why |
54+
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
55+
| **Roots** | Decide *where* an entity exists. See the **[Scenes & Roots](./scenes-and-roots.mdx)** page. |
56+
| **Behaviors** | Add logic to the entity. See the **[Behaviors](./behaviors.mdx)** page. |
57+
| **Authority** | Peer that owns simulation authority → `entity.authority` or `takeAuthority()`. |
58+
| **Events** | Pub-sub events such as `EntityDestroyed`, `EntityChildSpawned`. |
59+
| **Values** | Strong-typed, optionally replicated props. See the **[Synced Values and Adapters](./synced-values.mdx)** page. |
60+
| **Transform API** | `entity.transform` or shortcuts `entity.pos`, `entity.z`. |
61+
62+
### Accessing entities by name
63+
64+
`root._.<Name>` gives you a quick reference to any **direct child** under a root:
65+
66+
```ts
67+
const cam = game.local._.Camera; // generic Entity
68+
```
1669

17-
This list may not always be up-to-date. Refer to the Dreamlab Editor for a complete list of entities.
70+
The proxy returns an **untyped** `Entity`, so if you want type-specific methods
71+
(e.g. `Camera.zoom`), cast it:
1872

73+
```ts
74+
// get the local camera with full IntelliSense
75+
const cam = game.local._.Camera.cast(Camera);
76+
77+
cam.zoom = 2; // Camera-only API
78+
```
79+
80+
Dot-path chains work for grandchildren too:
81+
82+
```ts
83+
// Prefab » Player » Health
84+
const health = game.prefabs._.Player._.Health.cast(RichText);
85+
health.text = "HP: 100";
86+
```
87+
88+
> The lookup throws if the child name is wrong, so check your spelling against the scene graph panel.
89+
90+
---
91+
92+
## 3. Entity catalog (common types)
93+
94+
:::note
95+
This table is a quick reference—open the editor for the full, up-to-date list.
1996
:::
2097

2198
### General
2299

23-
| Entity | Usage |
24-
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
25-
| `AudioSource` | Play an audio clip. Optionally enable positional audio relative to the camera |
26-
| `Camera` | Refer to the dedicated [Camera page](./camera.mdx) of the engine manual |
27-
| `CharacterController` | Collider with dedicated character movement checks that prevent collision |
28-
| `Clickable` | Entity that emits a Signal when clicked on |
29-
| `Collider` | Solid collision for character controllers and other physics bodies |
30-
| `ComplexCollider` | Complex collision shape. Attach three or more empties as children for this to work. Forms a polygon from the children in CCW order |
31-
| `Empty` | Does nothing. Useful for attaching manager behaviors or marking positions (eg: spawnpoints) |
32-
| `RichText` | Draw Pixi.js Rich Text in the world |
33-
| `Rigidbody` | Entity that has simulated physics. Attach one or more colliders as children for this to work. |
100+
| Entity | Purpose |
101+
| --------------------- | ------------------------------------------------------------ |
102+
| `AudioSource` | Play sounds (optionally positional). |
103+
| `Camera` | Viewport controller—see the [Camera](./camera.mdx) page. |
104+
| `CharacterController` | Capsule collider with built-in movement checks. |
105+
| `Clickable` | Emits a signal when clicked. |
106+
| `Collider` | Basic physics collider. |
107+
| `ComplexCollider` | Polygon collider formed by 3 + child empties. |
108+
| `Empty` | Transform only—good for markers, parents, manager scripts. |
109+
| `RichText` | Draw PIXI rich text in-world. |
110+
| `Rigidbody` | Simulated physics body; attach one or more colliders. |
111+
| `Tilemap` | Create [Tilemaps](./tilemaps.mdx) using a predefined tileset |
112+
34113

35114
### Sprites
36115

37-
| Entity | Usage |
38-
| ---------------- | -------------------------------------------------------------------------------------- |
39-
| `AnimatedSprite` | Draws a JSON spritesheet as an animated image with configurable speed and frame range. |
40-
| `Sprite` | Draw an image in the world |
41-
| `TilingSprite` | Same as Sprite but with tiling options |
116+
| Entity | Purpose |
117+
| ---------------- | ---------------------------------------------------- |
118+
| `AnimatedSprite` | JSON spritesheet playback with speed / frame control |
119+
| `Sprite` | Draw a single image |
120+
| `TilingSprite` | Sprite that tiles its texture |
42121

43122
### UI
44123

45-
:::info
124+
| Entity | Purpose |
125+
| --------- | -------------------------------------------------------------- |
126+
| `UILayer` | Full-screen DOM tree—ideal for HUDs |
127+
| `UIPanel` | DOM tree fixed in world space (nameplates, signs, etc.) |
46128

47-
Visit the [User Interface page](./user-interface.mdx) of the engine manual for more info on HTML UI.
129+
### Graphics
48130

49-
:::
131+
| Entity | Purpose |
132+
| --------------- | ---------------------------------------- |
133+
| `RawPixi` | Advanced: draw via PIXI `Graphics` API |
134+
| `ColoredSquare` | Solid-color rectangle |
135+
| `ColoredPolygon`| Solid-color regular polygon |
50136

51-
| Entity | Usage |
52-
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
53-
| `UILayer` | Create an HTML DOM tree that covers the entire game screen. Useful for static UI elements (eg: HUD) |
54-
| `UIPanel` | Create an HTML DOM tree that exists in the world. Useful for UI elements that are fixed relative to the world (eg: signs, player nameplates, etc) |
137+
---
55138

56-
### Graphics
139+
## 4. Common entity events
140+
141+
Dreamlab uses events for entity lifecycle—subscribe with `entity.on(Event, handler)`.
57142

58-
| Entity | Usage |
59-
| ---------------- | --------------------------------------------------------------- |
60-
| `RawPixi` | **Advanced:** Draw using Pixi.js using their Graphics primitive |
61-
| `ColoredSquare` | Render a solid color rectangle in the world |
62-
| `ColoredPolygon` | Render a solid color regular polygon in the world |
143+
| Event | Fires when… |
144+
| ---------------------------- | -------------------------------------------------- |
145+
| `EntitySpawned` | the entity is first created (constructor done) |
146+
| `EntityDestroyed` | the entity is about to be removed |
147+
| `EntityChildSpawned` | a direct child is added |
148+
| `EntityDescendantDestroyed` | any level of descendant gets destroyed |
149+
| `EntityRenamed` | `entity.name` changes |
150+
| `EntityReparented` | `entity.parent` changes |
151+
| `EntityEnableChanged` | the effective `enabled` state toggles |

‎docs/guide/scenes-and-roots.mdx‎

Lines changed: 9 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -36,28 +36,14 @@ Each root decides **where** an entity exists and **who** runs its Behaviors.
3636

3737
---
3838

39-
### Spawning a prefab at runtime
39+
## Dot-path lookup (`root._.<Name>`)
4040

41-
A prefab lives under **`prefabs`** until you copy it into another root with `cloneInto()`.
41+
Every root (`world`, `local`, `server`, `prefabs`) exposes a **proxy** called `_.` that lets you
42+
grab children by name with dot-syntax.
4243

43-
```ts
44-
import { Behavior } from "@dreamlab/engine";
45-
46-
export default class CrateSpawner extends Behavior {
47-
spawnCrate() {
48-
// 1) choose the prefab
49-
const prefab = this.game.prefabs._.Crate;
50-
51-
// 2) choose the destination root (can be an entity)
52-
const parent = this.game.world;
53-
54-
// 3) clone it in; you can override name, authority, etc.
55-
const crate = prefab.cloneInto(parent, {
56-
name: "Crate." + crypto.randomUUID(),
57-
authority: this.game.network.self,
58-
});
59-
60-
// optional: move it somewhere
61-
crate.pos.set(10, 0, 5);
62-
}
63-
}
44+
| What you type | What it returns |
45+
| ------------------------------------------- | ---------------------------------- |
46+
| `game.prefabs._.Player` | The *Player* entity prefab |
47+
| `game.prefabs._.Player._.Health` | Child entity named *Health* |
48+
| `game.world._.Enemy42` | Runtime instance called *Enemy42* |
49+
| `game.local._.Camera` | The client-side camera |

0 commit comments

Comments
 (0)