Module Dynamic
Dynamics—short for dynamic objects—are for things that do not fit neatly into TheoTown's tile-based world.
Unlike buildings or trees, they are not tied to a particular tile: their position can change freely, making them useful for custom ships, flying objects and particle effects. They do not automatically interact with buildings, roads or other tile content; your script must handle any such interactions.
A dynamic object's position is given by three floating-point coordinates: x, y and z. X and y still use the familiar tile coordinate system, but fractional values let the object move between tiles. Z measures height above sea level; one unit is a terrain-height step (12 pixels before scaling).
Dynamics can be drawn at different heights, but their rendering order is still
relative to tiles: they appear either before or after a tile, not between all
of the objects occupying it. This can cause overlap issues near trees, buildings
or roads with cars and decorations. If needed, dynamic:setDepthBias() adjusts
rendering order without changing the object's actual position or height.
Each dynamic object belongs to the draft whose script spawned it. Only scripts
attached to that draft receive its dynamicInit, dynamicUpdate, dynamicDraw
and dynamicRemove callbacks. There is no function that returns a list of all
dynamic objects. Use Dynamic.forEach() or Dynamic.forEachInRangeXY() to visit
objects belonging to your draft. If you only need their number, use
Dynamic.count() instead: it reads a stored count and is much more efficient
than iterating over the objects.
Drawing and updating are independent: a call to script:dynamicUpdate() does
not imply a call to script:dynamicDraw(), or vice versa. Drawing is skipped
entirely when the object is outside its clipping radius or excluded by its LOD
setting. An object that is not visible may still update, but less often.
Defaults favor performance:
- Objects are volatile: they are not saved with the city.
- The update interval is approximately 40 ms, or longer when not visible.
- Objects are not drawn when zoomed out past the default LOD threshold of -1.
- Drawing is clipped by default using a radius of 80 pixels around the object.
Adjust these settings only when your object needs different behavior.
Call obj:remove() when an object should disappear, for example from
script:dynamicUpdate(obj, delta). Removal takes effect during an update.
Each object also has a storage table. For non-volatile objects, string-keyed
numbers, strings, booleans and nested tables can be saved; functions and userdata
are not serialized.
Dynamic objects were introduced in game version 1.13.00.
Usage:
-- Example for a tool draft: a marker drifts for two seconds after a click.
function script:click(x, y)
Dynamic.spawn(x + 0.5, y + 0.5, Tile.getTerrainHeight(x, y), { age = 0 })
end
function script:dynamicUpdate(obj, delta)
local storage = obj:getStorage()
storage.age = storage.age + delta -- delta is in milliseconds
obj:setX(obj:getX() + delta / 1000) -- move one tile per second
if storage.age >= 2000 then obj:remove() end
end
function script:dynamicDraw(obj)
Drawing.setDynamic(obj:getX(), obj:getY(), obj:getZ(), -2, -4)
Drawing.setColor(255, 255, 255)
Drawing.drawRect(0, 0, 4, 4)
end
Functions
| count () | Returns the number of dynamic objects owned by the calling draft. |
| forEach (foo) | Calls the function once for each active dynamic object owned by the calling draft. |
| forEachInRangeXY (x, y, radius, foo) | Calls the function for each active dynamic object within a horizontal radius of the given position. |
| spawn (x, y, z[, storage=nil]) | Creates a dynamic object owned by the calling draft. |
Class Dynamic
| dynamic:getClippingRadius () | Returns the radius used to clip drawing when the object is off-screen. |
| dynamic:getDepthBias () | Returns the adjustment to the object's drawing order relative to tiles. |
| dynamic:getLod () | Returns the minimum level of detail at which the object is drawn. |
| dynamic:getStorage () | Returns the object's storage table. |
| dynamic:getUpdateRate () | Returns the object's normal update interval. |
| dynamic:getX () | Returns the object's X position in tile coordinates. |
| dynamic:getY () | Returns the object's Y position in tile coordinates. |
| dynamic:getZ () | Returns the object's height above sea level in terrain-height steps. |
| dynamic:isVolatile () | Returns whether the object will be omitted when the city is saved. |
| dynamic:remove () | Marks the object for removal. |
| dynamic:setClippingRadius (radius) | Sets the off-screen clipping radius. |
| dynamic:setDepthBias (bias) | Adjusts drawing order relative to tiles without moving the object. |
| dynamic:setLod (lod) | Sets the minimum level of detail at which the object is drawn. |
| dynamic:setUpdateRate (rate) | Sets the normal update interval. |
| dynamic:setVolatile (volatile) | Sets whether the object is saved with the city. |
| dynamic:setX (x) | Sets the object's X position in tile coordinates. |
| dynamic:setY (y) | Sets the object's Y position in tile coordinates. |
| dynamic:setZ (z) | Sets the object's height above sea level in terrain-height steps. |
Class Script
| script:dynamicDraw (obj) | Called when a dynamic object is drawn. |
| script:dynamicInit (obj) | Called immediately after a new dynamic object is spawned. |
| script:dynamicRemove (obj) | Called when a dynamic object is removed during an update, after obj:remove(). |
| script:dynamicUpdate (obj, delta) | Called periodically for a dynamic object, even when it is not drawn. |
Functions
- count ()
-
Returns the number of dynamic objects owned by the calling draft.
Objects marked for removal remain counted until removal is processed.
Use this rather than iterating if you only need the count.
New feature:
-
This is a new feature that was added in version 1.13.00
Returns:
-
int
Number of registered dynamic objects.
- forEach (foo)
-
Calls the function once for each active dynamic object owned by the calling draft.
No list of objects is returned. Objects marked for removal are skipped.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- foo function Function called with each dynamic object.
- forEachInRangeXY (x, y, radius, foo)
-
Calls the function for each active dynamic object within a horizontal radius
of the given position. Height (z) is not considered.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- x number Center X in tile coordinates.
- y number Center Y in tile coordinates.
- radius number Radius in tiles.
- foo function Function called with each matching dynamic object.
- spawn (x, y, z[, storage=nil])
-
Creates a dynamic object owned by the calling draft. Its dynamicInit
callback is called immediately. Newly spawned objects are volatile by default.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- x number X position in tile coordinates.
- y number Y position in tile coordinates.
- z number Height above sea level in terrain-height steps.
- storage table Initial storage table; an empty table is created if omitted. (default nil)
Returns:
-
dynamic
The new dynamic object.
Class Dynamic
This type represents dynamic objects.- dynamic:getClippingRadius ()
-
Returns the radius used to clip drawing when the object is off-screen.
New feature:
-
This is a new feature that was added in version 1.13.00
Returns:
-
int
Clipping radius in pixels (80 by default).
- dynamic:getDepthBias ()
-
Returns the adjustment to the object's drawing order relative to tiles.
The bias does not affect the object's position or height.
New feature:
-
This is a new feature that was added in version 1.13.00
Returns:
-
int
Depth bias (0 by default).
- dynamic:getLod ()
-
Returns the minimum level of detail at which the object is drawn.
New feature:
-
This is a new feature that was added in version 1.13.00
Returns:
-
int
LOD threshold (-1 by default).
- dynamic:getStorage ()
-
Returns the object's storage table. Use it for state between callbacks.
Only serializable values survive saving a non-volatile object.
New feature:
-
This is a new feature that was added in version 1.13.00
Returns:
-
table
The storage table.
- dynamic:getUpdateRate ()
-
Returns the object's normal update interval. When not visible, updates may
run less often.
New feature:
-
This is a new feature that was added in version 1.13.00
Returns:
-
int
Update interval in milliseconds (40 by default).
- dynamic:getX ()
-
Returns the object's X position in tile coordinates.
New feature:
-
This is a new feature that was added in version 1.13.00
Returns:
-
number
X position.
- dynamic:getY ()
-
Returns the object's Y position in tile coordinates.
New feature:
-
This is a new feature that was added in version 1.13.00
Returns:
-
number
Y position.
- dynamic:getZ ()
-
Returns the object's height above sea level in terrain-height steps.
New feature:
-
This is a new feature that was added in version 1.13.00
Returns:
-
number
Height.
- dynamic:isVolatile ()
-
Returns whether the object will be omitted when the city is saved.
New feature:
-
This is a new feature that was added in version 1.13.00
Returns:
-
bool
True if the object is volatile (the default).
- dynamic:remove ()
-
Marks the object for removal. The dynamicRemove callback runs when the
object is actually removed during an update, not necessarily immediately.
New feature:
-
This is a new feature that was added in version 1.13.00
- dynamic:setClippingRadius (radius)
-
Sets the off-screen clipping radius. Increase it for large objects so they
do not disappear while part of them is still visible.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- radius int Clipping radius in pixels (80 by default).
- dynamic:setDepthBias (bias)
-
Adjusts drawing order relative to tiles without moving the object.
Use this to correct overlap issues, not to change its visual height.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- bias int Depth bias (0 by default).
- dynamic:setLod (lod)
-
Sets the minimum level of detail at which the object is drawn. Lower values
keep it visible when the city is zoomed further out.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- lod int LOD threshold (-1 by default).
- dynamic:setUpdateRate (rate)
-
Sets the normal update interval. Updates may run less often when the object
is not visible; choose a larger interval to reduce processing cost.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- rate int Update interval in milliseconds (40 by default).
- dynamic:setVolatile (volatile)
-
Sets whether the object is saved with the city. Non-volatile objects are
restored when the city is loaded, but dynamicInit is not called again.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- volatile bool True to omit the object from saves (the default).
- dynamic:setX (x)
-
Sets the object's X position in tile coordinates. Fractions are allowed.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- x number New X position.
- dynamic:setY (y)
-
Sets the object's Y position in tile coordinates. Fractions are allowed.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- y number New Y position.
- dynamic:setZ (z)
-
Sets the object's height above sea level in terrain-height steps.
This moves the object visually but does not change its drawing order.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- z number New height.
Class Script
Optional callbacks for dynamic objects owned by this script's draft. Define only the callbacks you need; the game invokes them as objects are spawned, updated, drawn or removed. Drawing and updating run independently.- script:dynamicDraw (obj)
-
Called when a dynamic object is drawn. Skipped when it is clipped or its LOD
threshold is not met; drawing and updating run independently.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- obj dynamic The object to draw.
- script:dynamicInit (obj)
-
Called immediately after a new dynamic object is spawned. Not called when
a non-volatile object is restored from a saved city.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- obj dynamic The new dynamic object.
- script:dynamicRemove (obj)
-
Called when a dynamic object is removed during an update, after
obj:remove().New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- obj dynamic The object being removed.
- script:dynamicUpdate (obj, delta)
-
Called periodically for a dynamic object, even when it is not drawn.
The first call can have a delta of 0; off-screen updates may be less frequent.
New feature:
-
This is a new feature that was added in version 1.13.00
Parameters:
- obj dynamic The object to update.
- delta int Milliseconds elapsed since its previous update.