Skip to content

Commit 4670ad8

Browse files
defold-servicesdefold-services
committed
Site changes [skip-ci]
1 parent 6353631 commit 4670ad8

File tree

2 files changed

+280
-2
lines changed

2 files changed

+280
-2
lines changed

‎llms-full.txt

Lines changed: 140 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1878,13 +1878,17 @@ You can interact with the editor using `editor` package that defines this API:
18781878
- for atlas animations: `images` (same as `images` in atlas)
18791879
- for tilemaps: `layers` (list of editor nodes for layers in the tilemap)
18801880
- for tilemap layers: `tiles` (an unbounded 2d grid of tiles), see `tilemap.tiles.*` for more info
1881+
- for particlefx: `emitters` (list of emitter editor nodes) and `modifiers` (list of modifier editor nodes)
1882+
- for particlefx emitters: `modifiers` (list of modifier editor nodes)
1883+
- for collision objects: `shapes` (list of collision shape editor nodes)
1884+
- for GUI files: `layers` (list of layer editor nodes)
18811885
- some properties that are shown in the Properties view when you have selected something in the Outline view. These types of outline properties supported:
18821886
- `strings`
18831887
- `booleans`
18841888
- `numbers`
18851889
- `vec2`/`vec3`/`vec4`
18861890
- `resources`
1887-
1891+
- `curves`
18881892
Please note that some of these properties might be read-only, and some might be unavailable in different contexts, so you should use `editor.can_get` before reading them and `editor.can_set` before making editor set them. Hover over property name in Properties view to see a tooltip with information about how this property is named in editor scripts. You can set resource properties to `nil` by supplying `""` value.
18891893
- `editor.can_get(node_id, property)` — check if you can get this property so `editor.get()` won't throw an error.
18901894
- `editor.can_set(node_id, property)` — check if `editor.tx.set()` transaction step with this property won't throw an error.
@@ -2091,6 +2095,141 @@ editor.transact({
20912095
})
20922096
```
20932097

2098+
#### Editing particlefx
2099+
2100+
You can edit particlefx using `modifiers` and `emitters` properties. For example, adding a circle emitter with acceleration modifier is done like this:
2101+
```lua
2102+
editor.transact({
2103+
editor.tx.add("/fire.particlefx", "emitters", {
2104+
type = "emitter-type-circle",
2105+
modifiers = {
2106+
{type = "modifier-type-acceleration"}
2107+
}
2108+
})
2109+
})
2110+
```
2111+
Many particlefx properties are curves or curve spreads (i.e. curve + some randomizer value). Curves are represented as a table with a non-empty list of `points`, where each point is a table with the following properties:
2112+
- `x` - the x coordinate of the point, should start at 0 and end at 1
2113+
- `y` - the value of the point
2114+
- `tx` (0 to 1) and `ty` (-1 to 1) - tangents of the point. E.g., for an 80-degree angle, `tx` should be `math.cos(math.rad(80))` and `ty` should be `math.sin(math.rad(80))`.
2115+
Curve spreads additionally have a `spread` number property.
2116+
2117+
For example, setting a particle lifetime alpha curve for an already existing emitter might look like this:
2118+
```lua
2119+
local emitter = editor.get("/fire.particlefx", "emitters")[1]
2120+
editor.transact({
2121+
editor.tx.set(emitter, "particle_key_alpha", { points = {
2122+
{x = 0, y = 0, tx = 0.1, ty = 1}, -- start at 0, go up quickly
2123+
{x = 0.2, y = 1, tx = 1, ty = 0}, -- reach 1 at 20% of a lifetime
2124+
{x = 1, y = 0, tx = 1, ty = 0} -- slowly go down to 0
2125+
}})
2126+
})
2127+
```
2128+
Of course, it's also possible to use the `particle_key_alpha` key in a table when creating an emitter. Additionally, you can use a single number instead to represent a "static" curve.
2129+
2130+
#### Editing collision objects
2131+
2132+
In addition to default outline properties, collision objects define `shapes` node list property. Adding new collision shapes is done like this:
2133+
```lua
2134+
editor.transact({
2135+
editor.tx.add("/hero.collisionobject", "shapes", {
2136+
type = "shape-type-box" -- or "shape-type-sphere", "shape-type-capsule"
2137+
})
2138+
})
2139+
```
2140+
Shape's `type` property is required during creation and cannot be changed after the shape is added. There are 3 shape types:
2141+
- `shape-type-box` - box shape with `dimensions` property
2142+
- `shape-type-sphere` - sphere shape with `diameter` property
2143+
- `shape-type-capsule` - capsule shape with `diameter` and `height` properties
2144+
2145+
#### Editing GUI files
2146+
2147+
In addition to outline properties, GUI nodes defines the following properties:
2148+
- `layers` — list of layer editor nodes (reorderable)
2149+
- `materials` — list of material editor nodes
2150+
2151+
It's possible to edit GUI layers using editor `layers` property, e.g.:
2152+
```lua
2153+
editor.transact({
2154+
editor.tx.add("/main.gui", "layers", {name = "foreground"}),
2155+
editor.tx.add("/main.gui", "layers", {name = "background"})
2156+
})
2157+
```
2158+
Additionally, it's possible to reorder layers:
2159+
```lua
2160+
local fg, bg = table.unpack(editor.get("/main.gui", "layers"))
2161+
editor.transact({
2162+
editor.tx.reorder("/main.gui", "layers", {bg, fg})
2163+
})
2164+
```
2165+
Similarly, fonts, materials, textures, and particlefxs are edited using `fonts`, `materials`, `textures`, and `particlefxs` properties:
2166+
```lua
2167+
editor.transact({
2168+
editor.tx.add("/main.gui", "fonts", {font = "/main.font"}),
2169+
editor.tx.add("/main.gui", "materials", {name = "shine", material = "/shine.material"}),
2170+
editor.tx.add("/main.gui", "particlefxs", {particlefx = "/confetti.material"}),
2171+
editor.tx.add("/main.gui", "textures", {texture = "/ui.atlas"})
2172+
})
2173+
```
2174+
These properties don't support reordering.
2175+
2176+
Finally, you can edit GUI nodes using `nodes` list property, e.g.:
2177+
```lua
2178+
editor.transact({
2179+
editor.tx.add("/main.gui", "nodes", {
2180+
type = "gui-node-type-box",
2181+
position = {20, 20, 20}
2182+
}),
2183+
editor.tx.add("/main.gui", "nodes", {
2184+
type = "gui-node-type-template",
2185+
template = "/button.gui"
2186+
}),
2187+
})
2188+
```
2189+
Built-in node types are:
2190+
- `gui-node-type-box`
2191+
- `gui-node-type-particlefx`
2192+
- `gui-node-type-pie`
2193+
- `gui-node-type-template`
2194+
- `gui-node-type-text`
2195+
2196+
If you are using spine extension, you can also use `gui-node-type-spine` node type.
2197+
2198+
If the GUI file defines layouts, you can get and set the values from layouts using `layout:property` syntax, e.g.:
2199+
```lua
2200+
local node = editor.get("/main.gui", "nodes")[1]
2201+
2202+
-- GET:
2203+
local position = editor.get(node, "position")
2204+
pprint(position) -- {20, 20, 20}
2205+
local landscape_position = editor.get(node, "Landscape:position")
2206+
pprint(landscape_position) -- {20, 20, 20}
2207+
2208+
-- SET:
2209+
editor.transact({
2210+
editor.tx.set(node, "Landscape:position", {30, 30, 30})
2211+
})
2212+
pprint(editor.get(node, "Landscape:position")) -- {30, 30, 30}
2213+
```
2214+
2215+
Layout properties that were set can be reset to their default values using `editor.tx.reset`:
2216+
```lua
2217+
print(editor.can_reset(node, "Landscape:position")) -- true
2218+
editor.transact({
2219+
editor.tx.reset(node, "Landscape:position")
2220+
})
2221+
```
2222+
Template node trees can be read, but not edited — you can only set node properties of the template node tree:
2223+
```lua
2224+
local template = editor.get("/main.gui", "nodes")[2]
2225+
print(editor.can_add(template, "nodes")) -- false
2226+
local node_in_template = editor.get(template, "nodes")[1]
2227+
editor.transact({
2228+
editor.tx.set(node_in_template, "text", "Button text")
2229+
})
2230+
print(editor.can_reset(node_in_template, "text")) -- true (overrides a value in the template)
2231+
```
2232+
20942233
### Use shell commands
20952234

20962235
Inside the `run` handler, you can write to files (using `io` module) and execute shell commands (using `editor.execute()` command). When executing shell commands, it's possible to capture the output of a shell command as a string and then use it in code. For example, if you want to make a command for formatting JSON that shells out to globally installed [`jq`](https://jqlang.github.io/jq/), you can write the following command:

‎manuals/editor-scripts.md

Lines changed: 140 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,13 +77,17 @@ You can interact with the editor using `editor` package that defines this API:
7777
- for atlas animations: `images` (same as `images` in atlas)
7878
- for tilemaps: `layers` (list of editor nodes for layers in the tilemap)
7979
- for tilemap layers: `tiles` (an unbounded 2d grid of tiles), see `tilemap.tiles.*` for more info
80+
- for particlefx: `emitters` (list of emitter editor nodes) and `modifiers` (list of modifier editor nodes)
81+
- for particlefx emitters: `modifiers` (list of modifier editor nodes)
82+
- for collision objects: `shapes` (list of collision shape editor nodes)
83+
- for GUI files: `layers` (list of layer editor nodes)
8084
- some properties that are shown in the Properties view when you have selected something in the Outline view. These types of outline properties supported:
8185
- `strings`
8286
- `booleans`
8387
- `numbers`
8488
- `vec2`/`vec3`/`vec4`
8589
- `resources`
86-
90+
- `curves`
8791
Please note that some of these properties might be read-only, and some might be unavailable in different contexts, so you should use `editor.can_get` before reading them and `editor.can_set` before making editor set them. Hover over property name in Properties view to see a tooltip with information about how this property is named in editor scripts. You can set resource properties to `nil` by supplying `""` value.
8892
- `editor.can_get(node_id, property)` — check if you can get this property so `editor.get()` won't throw an error.
8993
- `editor.can_set(node_id, property)` — check if `editor.tx.set()` transaction step with this property won't throw an error.
@@ -290,6 +294,141 @@ editor.transact({
290294
})
291295
```
292296

297+
#### Editing particlefx
298+
299+
You can edit particlefx using `modifiers` and `emitters` properties. For example, adding a circle emitter with acceleration modifier is done like this:
300+
```lua
301+
editor.transact({
302+
editor.tx.add("/fire.particlefx", "emitters", {
303+
type = "emitter-type-circle",
304+
modifiers = {
305+
{type = "modifier-type-acceleration"}
306+
}
307+
})
308+
})
309+
```
310+
Many particlefx properties are curves or curve spreads (i.e. curve + some randomizer value). Curves are represented as a table with a non-empty list of `points`, where each point is a table with the following properties:
311+
- `x` - the x coordinate of the point, should start at 0 and end at 1
312+
- `y` - the value of the point
313+
- `tx` (0 to 1) and `ty` (-1 to 1) - tangents of the point. E.g., for an 80-degree angle, `tx` should be `math.cos(math.rad(80))` and `ty` should be `math.sin(math.rad(80))`.
314+
Curve spreads additionally have a `spread` number property.
315+
316+
For example, setting a particle lifetime alpha curve for an already existing emitter might look like this:
317+
```lua
318+
local emitter = editor.get("/fire.particlefx", "emitters")[1]
319+
editor.transact({
320+
editor.tx.set(emitter, "particle_key_alpha", { points = {
321+
{x = 0, y = 0, tx = 0.1, ty = 1}, -- start at 0, go up quickly
322+
{x = 0.2, y = 1, tx = 1, ty = 0}, -- reach 1 at 20% of a lifetime
323+
{x = 1, y = 0, tx = 1, ty = 0} -- slowly go down to 0
324+
}})
325+
})
326+
```
327+
Of course, it's also possible to use the `particle_key_alpha` key in a table when creating an emitter. Additionally, you can use a single number instead to represent a "static" curve.
328+
329+
#### Editing collision objects
330+
331+
In addition to default outline properties, collision objects define `shapes` node list property. Adding new collision shapes is done like this:
332+
```lua
333+
editor.transact({
334+
editor.tx.add("/hero.collisionobject", "shapes", {
335+
type = "shape-type-box" -- or "shape-type-sphere", "shape-type-capsule"
336+
})
337+
})
338+
```
339+
Shape's `type` property is required during creation and cannot be changed after the shape is added. There are 3 shape types:
340+
- `shape-type-box` - box shape with `dimensions` property
341+
- `shape-type-sphere` - sphere shape with `diameter` property
342+
- `shape-type-capsule` - capsule shape with `diameter` and `height` properties
343+
344+
#### Editing GUI files
345+
346+
In addition to outline properties, GUI nodes defines the following properties:
347+
- `layers` — list of layer editor nodes (reorderable)
348+
- `materials` — list of material editor nodes
349+
350+
It's possible to edit GUI layers using editor `layers` property, e.g.:
351+
```lua
352+
editor.transact({
353+
editor.tx.add("/main.gui", "layers", {name = "foreground"}),
354+
editor.tx.add("/main.gui", "layers", {name = "background"})
355+
})
356+
```
357+
Additionally, it's possible to reorder layers:
358+
```lua
359+
local fg, bg = table.unpack(editor.get("/main.gui", "layers"))
360+
editor.transact({
361+
editor.tx.reorder("/main.gui", "layers", {bg, fg})
362+
})
363+
```
364+
Similarly, fonts, materials, textures, and particlefxs are edited using `fonts`, `materials`, `textures`, and `particlefxs` properties:
365+
```lua
366+
editor.transact({
367+
editor.tx.add("/main.gui", "fonts", {font = "/main.font"}),
368+
editor.tx.add("/main.gui", "materials", {name = "shine", material = "/shine.material"}),
369+
editor.tx.add("/main.gui", "particlefxs", {particlefx = "/confetti.material"}),
370+
editor.tx.add("/main.gui", "textures", {texture = "/ui.atlas"})
371+
})
372+
```
373+
These properties don't support reordering.
374+
375+
Finally, you can edit GUI nodes using `nodes` list property, e.g.:
376+
```lua
377+
editor.transact({
378+
editor.tx.add("/main.gui", "nodes", {
379+
type = "gui-node-type-box",
380+
position = {20, 20, 20}
381+
}),
382+
editor.tx.add("/main.gui", "nodes", {
383+
type = "gui-node-type-template",
384+
template = "/button.gui"
385+
}),
386+
})
387+
```
388+
Built-in node types are:
389+
- `gui-node-type-box`
390+
- `gui-node-type-particlefx`
391+
- `gui-node-type-pie`
392+
- `gui-node-type-template`
393+
- `gui-node-type-text`
394+
395+
If you are using spine extension, you can also use `gui-node-type-spine` node type.
396+
397+
If the GUI file defines layouts, you can get and set the values from layouts using `layout:property` syntax, e.g.:
398+
```lua
399+
local node = editor.get("/main.gui", "nodes")[1]
400+
401+
-- GET:
402+
local position = editor.get(node, "position")
403+
pprint(position) -- {20, 20, 20}
404+
local landscape_position = editor.get(node, "Landscape:position")
405+
pprint(landscape_position) -- {20, 20, 20}
406+
407+
-- SET:
408+
editor.transact({
409+
editor.tx.set(node, "Landscape:position", {30, 30, 30})
410+
})
411+
pprint(editor.get(node, "Landscape:position")) -- {30, 30, 30}
412+
```
413+
414+
Layout properties that were set can be reset to their default values using `editor.tx.reset`:
415+
```lua
416+
print(editor.can_reset(node, "Landscape:position")) -- true
417+
editor.transact({
418+
editor.tx.reset(node, "Landscape:position")
419+
})
420+
```
421+
Template node trees can be read, but not edited — you can only set node properties of the template node tree:
422+
```lua
423+
local template = editor.get("/main.gui", "nodes")[2]
424+
print(editor.can_add(template, "nodes")) -- false
425+
local node_in_template = editor.get(template, "nodes")[1]
426+
editor.transact({
427+
editor.tx.set(node_in_template, "text", "Button text")
428+
})
429+
print(editor.can_reset(node_in_template, "text")) -- true (overrides a value in the template)
430+
```
431+
293432
### Use shell commands
294433

295434
Inside the `run` handler, you can write to files (using `io` module) and execute shell commands (using `editor.execute()` command). When executing shell commands, it's possible to capture the output of a shell command as a string and then use it in code. For example, if you want to make a command for formatting JSON that shells out to globally installed [`jq`](https://jqlang.github.io/jq/), you can write the following command:

0 commit comments

Comments
 (0)