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.
generated by LDoc 1.4.3 Last updated 2026-11-22 20:27:39