Skip to content

Commit 2784db5

Browse files
CodedRedGITCodedRedGIT
committed
add more entity info to the entities page
1 parent f6f91d8 commit 2784db5

1 file changed

Lines changed: 351 additions & 28 deletions

File tree

‎docs/guide/entities.mdx‎

Lines changed: 351 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -109,43 +109,41 @@ This table is a quick reference—open the editor for the full, up-to-date list.
109109

110110
### General
111111

112-
| Entity | Purpose |
113-
| --------------------- | ------------------------------------------------------------ |
114-
| `AudioSource` | Play sounds (optionally positional). |
115-
| `Camera` | Viewport controller—see the [Camera](./camera.mdx) page. |
116-
| `CharacterController` | Capsule collider with built-in movement checks. |
117-
| `Clickable` | Emits a signal when clicked. |
118-
| `Collider` | Basic physics collider. |
119-
| `ComplexCollider` | Polygon collider formed by 3 + child empties. |
120-
| `Empty` | Transform only—good for markers, parents, manager scripts. |
121-
| `RichText` | Draw PIXI rich text in-world. |
122-
| `Rigidbody` | Simulated physics body; attach one or more colliders. |
123-
| `Tilemap` | Create [Tilemaps](./tilemaps.mdx) using a predefined tileset |
124-
112+
| Entity | Purpose |
113+
|--------|---------|
114+
| [`AudioSource`](#-audiosource) | Play sounds (optionally positional). |
115+
| [`Camera`](#-camera) | Viewport controller—see the [Camera](./camera.mdx) page. |
116+
| [`CharacterController`](#-charactercontroller) | Capsule collider with built-in movement checks. |
117+
| [`Clickable`](#-clickable) | Emits a signal when clicked. |
118+
| [`Collider`](#-collider) | Basic physics collider. |
119+
| [`ComplexCollider`](#-complexcollider) | Polygon collider formed by 3 + child empties. |
120+
| [`Empty`](#-empty) | Transform only—good for markers, parents, manager scripts. |
121+
| [`RichText`](#-richtext) | Draw PIXI rich text in-world. |
122+
| [`Rigidbody`](#%EF%B8%8F-rigidbody) | Simulated physics body; attach one or more colliders. |
123+
| [`Tilemap`](#%EF%B8%8F-tilemap) | Create [Tilemaps](./tilemaps.mdx) using a predefined tileset |
125124

126125
### Sprites
127126

128-
| Entity | Purpose |
129-
| ---------------- | ---------------------------------------------------- |
130-
| `AnimatedSprite` | JSON spritesheet playback with speed / frame control |
131-
| `Sprite` | Draw a single image |
132-
| `TilingSprite` | Sprite that tiles its texture |
127+
| Entity | Purpose |
128+
|--------|---------|
129+
| [`AnimatedSprite`](#%EF%B8%8F-animatedsprite) | JSON spritesheet playback with speed / frame control |
130+
| [`Sprite`](#%EF%B8%8F-sprite) | Draw a single image |
131+
| [`TilingSprite`](#%EF%B8%8F-tilingsprite) | Sprite that tiles its texture |
133132

134133
### UI
135134

136-
| Entity | Purpose |
137-
| --------- | -------------------------------------------------------------- |
138-
| `UILayer` | Full-screen DOM tree—ideal for HUDs |
139-
| `UIPanel` | DOM tree fixed in world space (nameplates, signs, etc.) |
135+
| Entity | Purpose |
136+
|--------|---------|
137+
| [`UILayer`](#-uilayer) | Full-screen DOM tree—ideal for HUDs |
138+
| [`UIPanel`](#-uipanel) | DOM tree fixed in world space (nameplates, signs, etc.) |
140139

141140
### Graphics
142141

143-
| Entity | Purpose |
144-
| --------------- | ---------------------------------------- |
145-
| `RawPixi` | Advanced: draw via PIXI `Graphics` API |
146-
| `ColoredSquare` | Solid-color rectangle |
147-
| `ColoredPolygon`| Solid-color regular polygon |
148-
142+
| Entity | Purpose |
143+
|--------|---------|
144+
| [`RawPixi`](#%EF%B8%8F-rawpixi) | Advanced: draw via PIXI `Graphics` API |
145+
| [`ColoredSquare`](#-coloredsquare) | Solid-color rectangle |
146+
| [`ColoredPolygon`](#-coloredpolygon) | Solid-color regular polygon |
149147
---
150148

151149
## 4. Common entity events
@@ -161,3 +159,328 @@ Dreamlab uses events for entity lifecycle—subscribe with `entity.on(Event, han
161159
| `EntityRenamed` | `entity.name` changes |
162160
| `EntityReparented` | `entity.parent` changes |
163161
| `EntityEnableChanged` | the effective `enabled` state toggles |
162+
163+
## 6 · Entities
164+
:::note
165+
This is a quick reference—open the editor for the full, up-to-date entity list.
166+
:::
167+
168+
### 🔊 AudioSource
169+
170+
**Howler.js** under the hood—handles both UI SFX and positional audio.
171+
172+
| Value | Purpose |
173+
|--------------|--------------------------------------------------------|
174+
| `clip` | Path to OGG / MP3 / WAV. |
175+
| `volume` | 0 … 1 |
176+
| `loop` | Loop forever. |
177+
| `minRange` | Distance (m) before attenuation starts. |
178+
| `maxRange` | Max audible distance; `-1` = infinite. |
179+
| `falloff` | 0 … 1 how quickly volume drops off. |
180+
| `stream` | Stream large music tracks vs. preloading. |
181+
182+
```ts
183+
const sfx = this.entity.cast(AudioSource);
184+
sfx.clip = "res://sfx/hit.ogg";
185+
sfx.play();
186+
```
187+
188+
---
189+
190+
### 🎥 Camera
191+
:::info Reference
192+
Detailed documentation is available on the [Camera](./camera.mdx) page.
193+
:::
194+
195+
The **Camera** is a *local-only* entity that controls what the player sees.
196+
197+
| Key value | Purpose / default |
198+
|------------------------|-------------------------------------------------|
199+
| `active` *(bool)* | When `true`, becomes the current viewport. Only **one** Camera can be active at a time. |
200+
| `zoom` *(number)* | 1 = 1 unit ≈ 1 metre on screen. Higher zooms **in**. |
201+
| `smooth` *(seconds)* | How long interpolation takes to catch up to the real transform. `0` = no smoothing. |
202+
| `lockAspectRatio` | Lock vertical / horizontal FOV, e.g. `[16, 9]`. |
203+
| `scaleFilterMode` | `"nearest"` or `"linear"`—overrides PIXI scale mode for crystal-clear pixel-art. |
204+
205+
---
206+
207+
### 🚶 CharacterController
208+
:::info Reference
209+
Detailed documentation is available on the [Physics](./physics.mdx) page.
210+
:::
211+
Kinematic platformer-style movement.
212+
213+
| API | Description |
214+
|-----------------------------|---------------------------------------|
215+
| `.isGrounded` *(getter)* | `true` when touching the ground. |
216+
| `.correctedPosition` | Position after resolving collisions. |
217+
| `.teleport = true` | Skip collision check on the next frame.|
218+
219+
```ts
220+
const ctrl = this.entity.cast(CharacterController);
221+
222+
if (ctrl.isGrounded && this.inputs.getKey("Space")) {
223+
ctrl.pos.y += 3; // jump impulse
224+
ctrl.teleport = true; // skip one collision frame
225+
}
226+
```
227+
228+
---
229+
230+
### 👆 Clickable
231+
232+
Creates an invisible hit-box that turns any entity into a UI button or trigger.
233+
234+
| Value / getter | Details |
235+
|----------------|---------|
236+
| `active` | Disable to ignore cursor & clicks. |
237+
| `shape` | `"Rectangle"` (default) or `"Circle"`. |
238+
| `width` / `height` | Rectangle size in metres. *(Only when `shape = "Rectangle"`)* |
239+
| `radius` / `innerRadius` | Outer & inner radii for ring-style targets. *(Only when `shape = "Circle"`)* |
240+
| `clicked` *(getter)* | `true` while the mouse button is held down over the entity. |
241+
| `hover` *(getter)* | `true` when the cursor is inside the bounds. |
242+
243+
244+
> Note — Clickable automatically changes the game canvas cursor to a
245+
pointer when any active Clickable is under the mouse.
246+
247+
---
248+
249+
### 🧱 Collider
250+
:::info Reference
251+
Detailed documentation is available on the [Physics](./physics.mdx) page.
252+
:::
253+
A **Collider** is a shape the physics engine can query.
254+
Attach to a `Rigidbody` **or** leave loose as a static trigger.
255+
256+
| Key value | Purpose |
257+
|----------------|------------------------------|
258+
| `shape` | `"Rectangle"` \| `"Circle"` *(capsule WIP)* |
259+
| `isSensor` | `true` → overlap events only; no collisions. |
260+
| `mass` | Used *only* if parented to a `Rigidbody`. |
261+
262+
---
263+
264+
### 🧱 ComplexCollider
265+
:::info Reference
266+
Detailed documentation is available on the [Physics](./physics.mdx) page.
267+
:::
268+
A **concave** (multi-polygon) collider built from its children’s positions.
269+
Perfect for arbitrary terrain outlines.
270+
271+
| Value | Purpose |
272+
|------------|---------------------------------------|
273+
| `isSensor` | Trigger only, no physical response. |
274+
| `mass` | Used if parented to a `Rigidbody`. |
275+
276+
**How it works**
277+
278+
1. Sorts direct children (`Child.0`, `Child.1`, …).
279+
2. Runs **poly-decomp** to split into convex pieces.
280+
3. Creates one Rapier collider per piece (auto-updates on transform / re-parent).
281+
282+
> **Tip:** Keep the child points roughly in order (clockwise or CCW) for best results.
283+
284+
---
285+
286+
### 📦 Empty
287+
288+
An entity with **only a Transform**.
289+
Use it as a pivot, folder, or to attach scripts that don't need graphics / physics.
290+
291+
---
292+
293+
### 🔡 RichText
294+
295+
Renders a PIXI **Text** with full CSS-like styling.
296+
297+
| Value | Details |
298+
|--------------------|-------------------------------------------------------------------|
299+
| `text` | Plain string or BBCode (*coming soon*). |
300+
| `fontFamily` | Any web-safe or imported font (async-loads on first use). |
301+
| `fontSize` | In pixels. Remaps to metres via entity scale. |
302+
| `fontStyle` | `"normal" \| `"italic"` \| `"oblique"`. |
303+
| `fontWeight` | `"bold"` or numeric `100`–`900`. |
304+
| `align` | `"left"`, `"center"`, `"right"` (auto-sets anchor). |
305+
| `color` | Fill colour. |
306+
| `stroke` | Toggle outline; reveals `strokeColor`, `strokeWidth`, `strokeJoin`.|
307+
| `scaleFilterMode` | `"default"` → inherit Camera; otherwise `"nearest"` / `"linear"`. |
308+
309+
```ts
310+
const label = this.game.local._.ui.spawn({ name: "label", type: RichText });
311+
label.text = "FPS: 60";
312+
label.fontSize = 24;
313+
label.color = "#00ff00";
314+
label.stroke = true;
315+
label.strokeColor = "black";
316+
```
317+
318+
---
319+
320+
### ⚙️ Rigidbody
321+
:::info Reference
322+
Detailed documentation is available on the [Physics](./physics.mdx) page.
323+
:::
324+
Creates a Rapier **RigidBody** and re-parents all child Colliders automatically.
325+
326+
| Value | Description |
327+
|-------|---------------------------------|
328+
| `type`| `"dynamic"` (default) or `"fixed"`. |
329+
330+
---
331+
332+
### 🗺️ Tilemap
333+
:::info Reference
334+
Detailed documentation is available on the [Tilemap](./tilemaps.mdx) page.
335+
:::
336+
A grid of palette IDs rendered via an atlas. Great for terrains & dungeons.
337+
338+
| Handy method | What it does |
339+
|----------------------------------|-------------------------------------------|
340+
| `setTile(x, y, paletteId?)` | Draw / erase a cell (`undefined` = erase) |
341+
| `getTile(x, y)` | Return `TileData` or `undefined`. |
342+
| `getTileAtPoint(worldPos)` | Ray-cast the cursor to a tile. |
343+
| `clearTiles()` | Erase everything. |
344+
| `tiles()` *(generator)* | Iterate `{ x, y, tile }` of filled cells. |
345+
346+
---
347+
348+
### 🖼️ AnimatedSprite
349+
350+
Plays frames from **JSON spritesheets** *or* chops a grid into frames on the fly.
351+
352+
| Value | Details |
353+
|----------------------|-----------------------------------------------------------------|
354+
| `jsonSpritesheet` | Path to *.json* exported by Aseprite / TexturePacker. |
355+
| `spritesheet` | Plain PNG; sliced by `frameDimensions`. |
356+
| `speed` | Frames per second (default `0.1`). |
357+
| `startFrame`/`endFrame` | Clamp playback range; `endFrame = -1` ➜ to last frame. |
358+
| `loop` | When `false`, stops on last frame. |
359+
360+
```ts
361+
const anim = this.entity.cast(AnimatedSprite);
362+
anim.spritesheet = "res://run.png";
363+
anim.frameDimensions.set(128, 128);
364+
anim.speed = 0.2;
365+
```
366+
367+
---
368+
369+
### 🖼️ Sprite
370+
371+
Draw a single texture, with optional **letter-box preserve-aspect**.
372+
373+
| Value | Purpose |
374+
|------------------------|--------------------------------------------------------|
375+
| `texture` | Image path. Empty ⇒ white 1 × 1 pixel. |
376+
| `width` / `height` | Target size in metres. |
377+
| `preserveAspectRatio` | `true` ⇒ maintains original proportions (letterbox). |
378+
| `tint` / `alpha` | Standard PIXI tint & transparency. |
379+
380+
---
381+
382+
### 🖼️ TilingSprite
383+
384+
Repeats a texture infinitely—ideal for parallax backdrops, water, conveyor belts…
385+
386+
| Value | Details |
387+
|-------------------|--------------------------------------------------------------|
388+
| `texture` | Tile image. |
389+
| `tilePosition` | Scroll offset—animate for parallax. |
390+
| `tileScale` | Per-axis scaling *before* fit into entity `width`/`height`. |
391+
| `tileRotation` | Rotation of the pattern in **radians**. |
392+
| `width` / `height`| Drawn size in metres. |
393+
| `tint` / `alpha` | Standard PIXI properties. |
394+
395+
```ts
396+
const water = this.game.local._.MyTilingSprite.cast(TilingSprite);
397+
water.onFrame = () => water.tilePosition.x += 0.02; // gentle flow
398+
```
399+
400+
---
401+
402+
### 🎨 UILayer
403+
:::info Reference
404+
Detailed documentation is available on the [User Interface](./user-interface.mdx) page.
405+
:::
406+
Full-screen DOM overlay—great for HUDs, menus, or drag-and-drop editors.
407+
408+
* Lives in its own **Shadow DOM** to avoid CSS bleed.
409+
* Pointer-events are disabled by default; enable per-element.
410+
* `dom` → ShadowRoot, `element` → root `<div>` inside the layer.
411+
412+
> Position & scale **follow the canvas**, not the world.
413+
414+
---
415+
416+
### 🎨 UIPanel
417+
418+
DOM **anchored to an entity** in world space (nameplates, shop signs, speech bubbles).
419+
420+
| Feature | How it works |
421+
|---------------------|----------------------------------------------------------|
422+
| **Screen lock** | Re-projects each frame via `Camera.worldToScreen()`. |
423+
| **Transform aware** | Honors entity position/rotation/scale (plus Camera zoom).|
424+
| **Shadow DOM** | Same isolation as `UILayer`. |
425+
426+
---
427+
428+
### 🖌️ RawPixi
429+
:::info Reference
430+
Detailed documentation is available on the [Rendering with Pixi](./rendering.mdx) page.
431+
:::
432+
Low-level access to PIXI—attach your own `Graphics` / `Sprite` objects.
433+
434+
```ts
435+
const raw = this.game.local.spawn({ name: "graphic", type: RawPixi });
436+
437+
// Draw a circle each frame
438+
raw.onFrame = function () {
439+
if (!this.container) return;
440+
const g = this.container.getChildAt(0) as PIXI.Graphics ?? new PIXI.Graphics();
441+
if (!g.parent) this.container.addChild(g);
442+
443+
g.clear().circle(0, 0, 0.5).fill("hotpink");
444+
};
445+
```
446+
447+
`RawGraphics` is an alias kept for legacy scenes; new projects should use **RawPixi**.
448+
449+
---
450+
451+
### 🟩 ColoredSquare
452+
453+
Simplest possible PIXI rectangle.
454+
455+
| Value | Details |
456+
|-------------------|----------------|
457+
| `width` / `height`| Size in metres |
458+
| `color` | Fill colour |
459+
| `tint` | Tint multiplier|
460+
461+
```ts
462+
const box = this.game.world.spawn({ name: "square", type: ColoredSquare });
463+
box.width = 5;
464+
box.height = 0.5;
465+
box.color = "#ffffff";
466+
```
467+
---
468+
469+
### 🟢 ColoredPolygon
470+
471+
Draws a filled **n-gon** directly in PIXI. Great for quick proto art or hit flashes.
472+
473+
| Value | Details |
474+
|---------------------|-------------------------------------------------|
475+
| `sides` | 3 – 1000 edges. |
476+
| `width` / `height` | Size in metres (scales with entity transform). |
477+
| `color` | Fill colour (`#rrggbb`, `rgba()`, or CSS name). |
478+
| `tint` | Post-multiply tint (palette swaps / hit-flash). |
479+
480+
```ts
481+
const poly = this.game.local.spawn({ name: "hexagon", type: ColoredPolygon });
482+
poly.sides = 6; // hexagon
483+
poly.width = poly.height = 2;
484+
poly.color = "#ffcc00";
485+
poly.tint = "#ff8800";
486+
```

0 commit comments

Comments
 (0)