probe
This commit is contained in:
@@ -5,229 +5,91 @@ type: docs
|
||||
|
||||
# draw2d
|
||||
|
||||
A collection of retained-mode 2D drawing factories. Each factory creates an object that auto-registers with `film2d` and renders via the compositor. Destroy objects when no longer needed.
|
||||
|
||||
A collection of 2D drawing functions that operate in screen space. Provides primitives
|
||||
for lines, rectangles, text, sprite drawing, etc.
|
||||
```javascript
|
||||
var draw = use('draw2d')
|
||||
```
|
||||
|
||||
## Factories
|
||||
|
||||
### point(pos, size, color) <sub>function</sub>
|
||||
### draw.sprite(props)
|
||||
|
||||
Create a sprite from an image. Auto-registers with `film2d`.
|
||||
|
||||
```javascript
|
||||
var s = draw.sprite({
|
||||
image: "hero.png",
|
||||
pos: {x: 100, y: 200},
|
||||
width: 32, height: 32,
|
||||
plane: 'game', layer: 0
|
||||
})
|
||||
s.destroy() // remove from renderer
|
||||
```
|
||||
|
||||
See `sprite.cm` for full property list: `pos`, `image`, `width`, `height`, `anchor_x`, `anchor_y`, `rotation`, `color`, `opacity`, `tint`, `filter`, `plane`, `layer`, `groups`, `visible`, `flip`, `fit`, `uv`.
|
||||
|
||||
**pos**: A 2D position ([x, y]) where the point should be drawn.
|
||||
### draw.shape.rect(props) / circle(props) / ellipse(props) / pill(props)
|
||||
|
||||
**size**: The size of the point (not currently affecting rendering).
|
||||
Create SDF shapes. Supports fill, stroke, rounded corners, dashing, feathering, and texture fill.
|
||||
|
||||
**color**: The color of the point, defaults to Color.blue.
|
||||
```javascript
|
||||
var box = draw.shape.rect({
|
||||
pos: {x: 50, y: 50}, width: 100, height: 60,
|
||||
fill: {r: 1, g: 0, b: 0, a: 1},
|
||||
stroke: {r: 1, g: 1, b: 1, a: 1}, stroke_thickness: 2,
|
||||
radius: 8,
|
||||
plane: 'game'
|
||||
})
|
||||
|
||||
var ball = draw.shape.circle({
|
||||
pos: {x: 200, y: 200}, radius: 16,
|
||||
fill: {r: 0, g: 1, b: 0, a: 1},
|
||||
plane: 'game', groups: ['glow']
|
||||
})
|
||||
```
|
||||
|
||||
**Returns**: None
|
||||
Properties: `shape_type`, `pos`, `width`, `height`, `radius`, `corner_style`, `feather`, `stroke_thickness`, `stroke_align`, `dash_len`, `gap_len`, `dash_offset`, `cap`, `join`, `fill`, `stroke`, `blend`, `opacity`, `fill_tex`, `uv`, `plane`, `layer`, `groups`, `visible`.
|
||||
|
||||
### draw.text(props)
|
||||
|
||||
### line(points, color, thickness, pipeline) <sub>function</sub>
|
||||
Create a text label. Updates live when you change `.text`.
|
||||
|
||||
```javascript
|
||||
var label = draw.text({
|
||||
text: "Score: 0",
|
||||
pos: {x: 10, y: 500},
|
||||
font: "fonts/dos", size: 16,
|
||||
color: {r: 1, g: 1, b: 1, a: 1},
|
||||
plane: 'hud'
|
||||
})
|
||||
label.text = "Score: 42" // updates on next frame
|
||||
```
|
||||
|
||||
### draw.tilemap(props)
|
||||
|
||||
Create a tile-based map. See `tilemap2d.cm`.
|
||||
|
||||
**points**: An array of 2D positions representing the line vertices.
|
||||
### draw.anim(props)
|
||||
|
||||
**color**: The color of the line, default Color.white.
|
||||
Create an animated sprite from an aseprite/gif file. Auto-plays if the image has frames.
|
||||
|
||||
**thickness**: The line thickness, default 1.
|
||||
```javascript
|
||||
var anim = draw.anim({
|
||||
image: "hero.aseprite",
|
||||
pos: {x: 100, y: 100},
|
||||
plane: 'game'
|
||||
})
|
||||
anim.play("walk") // play named animation
|
||||
anim.stop() // pause
|
||||
anim.resume() // resume
|
||||
anim.update(dt) // advance frame (call from update loop)
|
||||
```
|
||||
|
||||
**pipeline**: (Optional) A pipeline or rendering state object.
|
||||
## Lifecycle
|
||||
|
||||
All draw2d objects register with `film2d` on creation. Call `.destroy()` to unregister and remove from rendering. Set `.visible = false` to hide without destroying.
|
||||
|
||||
**Returns**: None
|
||||
|
||||
|
||||
### cross(pos, size, color, thickness, pipe) <sub>function</sub>
|
||||
|
||||
|
||||
|
||||
|
||||
**pos**: The center of the cross as a 2D position ([x, y]).
|
||||
|
||||
**size**: Half the size of each cross arm.
|
||||
|
||||
**color**: The color of the cross, default Color.red.
|
||||
|
||||
**thickness**: The thickness of each line, default 1.
|
||||
|
||||
**pipe**: (Optional) A pipeline or rendering state object.
|
||||
|
||||
|
||||
**Returns**: None
|
||||
|
||||
|
||||
### arrow(start, end, color, wingspan, wingangle, pipe) <sub>function</sub>
|
||||
|
||||
|
||||
|
||||
|
||||
**start**: The start position of the arrow ([x, y]).
|
||||
|
||||
**end**: The end (tip) position of the arrow ([x, y]).
|
||||
|
||||
**color**: The color, default Color.red.
|
||||
|
||||
**wingspan**: The length of each arrowhead 'wing', default 4.
|
||||
|
||||
**wingangle**: Wing rotation in degrees, default 10.
|
||||
|
||||
**pipe**: (Optional) A pipeline or rendering state object.
|
||||
|
||||
|
||||
**Returns**: None
|
||||
|
||||
|
||||
### rectangle(rect, color, pipeline) <sub>function</sub>
|
||||
|
||||
|
||||
|
||||
|
||||
**rect**: A rectangle object with {x, y, width, height}.
|
||||
|
||||
**color**: The fill color, default Color.white.
|
||||
|
||||
**pipeline**: (Optional) A pipeline or rendering state object.
|
||||
|
||||
|
||||
**Returns**: None
|
||||
|
||||
|
||||
### tile(image, rect, color, tile, pipeline) <sub>function</sub>
|
||||
|
||||
|
||||
:raises Error: If no image is provided.
|
||||
|
||||
|
||||
**image**: An image object or string path to a texture.
|
||||
|
||||
**rect**: A rectangle specifying draw location/size ({x, y, width, height}).
|
||||
|
||||
**color**: The color tint, default Color.white.
|
||||
|
||||
**tile**: A tiling definition ({repeat_x, repeat_y}), default tile_def.
|
||||
|
||||
**pipeline**: (Optional) A pipeline or rendering state object.
|
||||
|
||||
|
||||
**Returns**: None
|
||||
|
||||
|
||||
### slice9(image, rect, slice, color, info, pipeline) <sub>function</sub>
|
||||
|
||||
|
||||
:raises Error: If no image is provided.
|
||||
|
||||
|
||||
**image**: An image object or string path to a texture.
|
||||
|
||||
**rect**: A rectangle specifying draw location/size, default [0, 0].
|
||||
|
||||
**slice**: The pixel inset or spacing for the 9-slice (number or object).
|
||||
|
||||
**color**: The color tint, default Color.white.
|
||||
|
||||
**info**: A slice9 info object controlling tiling of edges/corners.
|
||||
|
||||
**pipeline**: (Optional) A pipeline or rendering state object.
|
||||
|
||||
|
||||
**Returns**: None
|
||||
|
||||
|
||||
### image(image, rect, rotation, color, pipeline) <sub>function</sub>
|
||||
|
||||
|
||||
:raises Error: If no image is provided.
|
||||
|
||||
|
||||
**image**: An image object or string path to a texture.
|
||||
|
||||
**rect**: A rectangle specifying draw location/size, default [0,0]; width/height default to image size.
|
||||
|
||||
**rotation**: Rotation in degrees (not currently used).
|
||||
|
||||
**color**: The color tint, default none.
|
||||
|
||||
**pipeline**: (Optional) A pipeline or rendering state object.
|
||||
|
||||
|
||||
**Returns**: A sprite object that was created for this draw call.
|
||||
|
||||
|
||||
### images(image, rects, config) <sub>function</sub>
|
||||
|
||||
|
||||
:raises Error: If no image is provided.
|
||||
|
||||
|
||||
**image**: An image object or string path to a texture.
|
||||
|
||||
**rects**: An array of rectangle objects ({x, y, width, height}) to draw.
|
||||
|
||||
**config**: (Unused) Additional config data if needed.
|
||||
|
||||
|
||||
**Returns**: An array of sprite objects created and queued for rendering.
|
||||
|
||||
|
||||
### sprites(sprites, sort, pipeline) <sub>function</sub>
|
||||
|
||||
|
||||
|
||||
|
||||
**sprites**: An array of sprite objects to draw.
|
||||
|
||||
**sort**: Sorting mode or order, default 0.
|
||||
|
||||
**pipeline**: (Optional) A pipeline or rendering state object.
|
||||
|
||||
|
||||
**Returns**: None
|
||||
|
||||
|
||||
### circle(pos, radius, color, inner_radius, pipeline) <sub>function</sub>
|
||||
|
||||
|
||||
|
||||
|
||||
**pos**: Center of the circle ([x, y]).
|
||||
|
||||
**radius**: The circle radius.
|
||||
|
||||
**color**: The fill color of the circle, default none.
|
||||
|
||||
**inner_radius**: (Unused) Possibly ring thickness, default 1.
|
||||
|
||||
**pipeline**: (Optional) A pipeline or rendering state object.
|
||||
|
||||
|
||||
**Returns**: None
|
||||
|
||||
|
||||
### text(text, rect, font, size, color, wrap, pipeline) <sub>function</sub>
|
||||
|
||||
|
||||
|
||||
|
||||
**text**: The string to draw.
|
||||
|
||||
**rect**: A rectangle specifying draw position (and possibly wrapping area).
|
||||
|
||||
**font**: A font object or string path, default sysfont.
|
||||
|
||||
**size**: (Unused) Possibly intended for scaling the font size.
|
||||
|
||||
**color**: The text color, default Color.white.
|
||||
|
||||
**wrap**: Pixel width for text wrapping, default 0 (no wrap).
|
||||
|
||||
**pipeline**: (Optional) A pipeline or rendering state object.
|
||||
|
||||
|
||||
**Returns**: None
|
||||
## Planes and Groups
|
||||
|
||||
Every drawable has a `plane` (string) and optional `groups` (array of strings). The compositor renders drawables per-plane. Groups route drawables through effects (bloom, mask, etc.).
|
||||
|
||||
@@ -105,13 +105,58 @@ Each system module provides behavior that operates on the entity's data. No clas
|
||||
|
||||
## Querying Entities
|
||||
|
||||
The world module lets you find entities:
|
||||
The world module provides several ways to find and iterate entities:
|
||||
|
||||
```javascript
|
||||
var world = use('world')
|
||||
|
||||
// All entities are tracked internally
|
||||
// Query patterns are still being developed
|
||||
// Iterate all entities
|
||||
world.each(function(entity) {
|
||||
log.console(entity)
|
||||
})
|
||||
|
||||
// Filter entities by predicate — returns array
|
||||
var enemies = world.query(function(e) { return e.team == 'enemy' })
|
||||
|
||||
// Find first matching entity
|
||||
var player = world.find(function(e) { return e.is_player })
|
||||
|
||||
// Get entity count
|
||||
var n = world.count()
|
||||
```
|
||||
|
||||
## Updating Entities
|
||||
|
||||
Call `world.update(dt)` each frame to tick all entities that have an `update(dt)` method:
|
||||
|
||||
```javascript
|
||||
// In your core.start() update callback:
|
||||
core.start({
|
||||
update: function(dt) {
|
||||
world.update(dt)
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
## Loading Levels
|
||||
|
||||
Load a level from a JSON array of entity definitions:
|
||||
|
||||
```javascript
|
||||
world.load_level([
|
||||
{"script": "entities/goblin", "pos": {"x": 100, "y": 200}},
|
||||
{"script": "entities/tree", "pos": {"x": 300, "y": 100}}
|
||||
])
|
||||
```
|
||||
|
||||
Each entry's `script` field is loaded via `use()` as the prototype. All other fields are applied as overrides.
|
||||
|
||||
## Clearing the World
|
||||
|
||||
Remove and destroy all entities:
|
||||
|
||||
```javascript
|
||||
world.clear()
|
||||
```
|
||||
|
||||
## Override Rules
|
||||
|
||||
@@ -28,10 +28,13 @@ Prosperon is not a monolithic engine with a global state object. It is a collect
|
||||
| `compositor` | Build render plans from scene configs |
|
||||
| `input` | Action mapping, device routing |
|
||||
| `sound` | Audio playback |
|
||||
| `world` | Entity management |
|
||||
| `world` | Entity management (add, query, update, levels) |
|
||||
| `camera` | Viewport into the world |
|
||||
| `draw2d` | Re-exports sprite, shape, text, tilemap, anim |
|
||||
| `text2d` | Text rendering |
|
||||
| `shape2d` | SDF shapes |
|
||||
| `shape2d` | SDF shapes (rect, circle, ellipse, pill) |
|
||||
| `anim2d` | Sprite animation playback (aseprite/gif) |
|
||||
| `collision2d` | AABB + circle overlap queries |
|
||||
| `tilemap2d` | Grid-based tile rendering |
|
||||
| `tween` | Value interpolation |
|
||||
| `resources` | Asset path resolution |
|
||||
|
||||
Reference in New Issue
Block a user