Skip to Content
defold-typescript libraries
dev-masih

dev-masih/defarmy

Groups game objects (soldiers) into armies, places them in a built-in or customized pattern, and moves and rotates each army as a group. Create an army with army_create and a soldier for each game object with soldier_create, then call soldier_move from each soldier's update and apply the position and rotation it returns.

  • GitHub: dev-masih/defarmy — pinned to v1
    1. Pick a release from dev-masih/defarmy releases and add its Source code (zip) URL (or a packaged .zip asset, if the library ships one) to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as defarmy from "defarmy.defarmy"

Functions

army_create(army_center_position: Vector3, army_initial_rotation: Quaternion, member_padding: number, is_sticky: boolean, army_pattern: Hash, pattern_func?: PatternFunc): number

Creates a group of game objects (an army) with the given member padding and pattern, and returns its id. PATTERN.CUSTOMIZED requires pattern_func, which upstream asserts, and every other pattern ignores it. Any value outside PATTERN fails an assert.

Parameters

  • army_center_position: Vector3 — The army's center position.
  • army_initial_rotation: Quaternion — The army's initial rotation.
  • member_padding: number — The distance between members.
  • is_sticky: boolean — Whether members are glued to their places in the army, rather than following them. It shows most while the army rotates.
  • army_pattern: Hash — One of PATTERN.
  • pattern_func?: PatternFunc — Builds the rows for PATTERN.CUSTOMIZED.

Returns

  • number

army_members(army_id: number): number[]

Returns the ids of the soldiers in an army. The list is the army's own, so editing it edits the army.

Parameters

  • army_id: number — The army's id.

Returns

  • number[]

army_remove(army_id: number)

Removes an army and releases its members, which stay as soldiers in no army.

Parameters

  • army_id: number — The army's id.

army_update_position(army_id: number, army_center_position: Vector3)

Moves an army's center.

Parameters

  • army_id: number — The army's id.
  • army_center_position: Vector3 — The new center position.

army_update_rotation(army_id: number, army_rotation: Quaternion)

Rotates an army.

Parameters

  • army_id: number — The army's id.
  • army_rotation: Quaternion — The new rotation.

army_update_pattern(army_id: number, army_pattern: Hash, pattern_func?: PatternFunc)

Changes an army's pattern and rearranges its members at once. PATTERN.CUSTOMIZED requires pattern_func, which upstream asserts, and every other pattern ignores it.

Parameters

  • army_id: number — The army's id.
  • army_pattern: Hash — One of PATTERN.
  • pattern_func?: PatternFunc — Builds the rows for PATTERN.CUSTOMIZED.

army_update_stickiness(army_id: number, is_sticky: boolean)

Changes whether an army's members are glued to their places in it.

Parameters

  • army_id: number — The army's id.
  • is_sticky: boolean — Whether members are glued to their places, rather than following them.

army_debug_draw(army_id: number, debug_color: Vector4)

Draws an army's center and facing for one frame, by posting draw_line to @render:. Call it every frame to keep it shown.

Parameters

  • army_id: number — The army's id.
  • debug_color: Vector4 — The color of the lines.

soldier_create(position: Vector3, initial_direction: Vector3, army_id?: number): number

Creates a soldier and returns its id, joining it to an army when army_id is given.

Parameters

  • position: Vector3 — The soldier's current position.
  • initial_direction: Vector3 — The direction the soldier's game object faces at zero rotation. Every rotation soldier_move returns is relative to it.
  • army_id?: number — The army to join.

Returns

  • number

soldier_join_army(soldier_id: number, army_id: number)

Moves a soldier into an army, out of the army it was in.

Parameters

  • soldier_id: number — The soldier's id.
  • army_id: number — The army's id.

soldier_leave_army(soldier_id: number)

Takes a soldier out of its army and rearranges the members left. A soldier in no army is left as it is. At v1 the rearrangement raises a Lua error when the soldier was the army's last member, so call army_remove instead in that case.

Parameters

  • soldier_id: number — The soldier's id.

soldier_remove(soldier_id: number)

Removes a soldier completely, rearranging the army it was in. soldier_move then returns undefined for both values. At v1 the rearrangement raises a Lua error when the soldier was the army's last member, so call army_remove first in that case.

Parameters

  • soldier_id: number — The soldier's id.

soldier_debug_on(soldier_id: number, debug_color: Vector4)

Turns on a soldier's debug marks: each soldier_move call then posts draw_line to @render: to mark the position the soldier is heading for with a cross.

Parameters

  • soldier_id: number — The soldier's id.
  • debug_color: Vector4 — The color of the marks.

soldier_debug_off(soldier_id: number)

Turns off a soldier's debug marks.

Parameters

  • soldier_id: number — The soldier's id.

soldier_move(soldier_id: number, current_position: Vector3, speed: number, threshold?: number): LuaMultiReturn<[ Vector3, Quaternion ] | [ undefined, undefined ]>

Calculates a soldier's next position and rotation, moving it toward its place in its army. A soldier in no army keeps current_position. Returns undefined for both values once the soldier is removed: const [position, rotation] = defarmy.soldier_move(id, go.get_position(), speed).

Parameters

  • soldier_id: number — The soldier's id.
  • current_position: Vector3 — The soldier's current position.
  • speed: number — How far the soldier moves this call.
  • threshold?: number — The distance from its place within which the soldier counts as placed. Defaults to 1.

Returns

  • LuaMultiReturn<[ Vector3, Quaternion ] | [ undefined, undefined ]>

Variables

PATTERN: { BOTTOM_TO_TOP_SQUARE: Hash; TOP_TO_BOTTOM_SQUARE: Hash; TRIANGLE: Hash; RHOMBUS_TALL: Hash; RHOMBUS_SHORT: Hash; CUSTOMIZED: Hash; }

The army patterns army_create and army_update_pattern take. The five named patterns place the soldiers in built-in shapes. CUSTOMIZED takes its rows from the pattern_func passed beside it.

Types

type PatternFunc = (total_count: number) => number[]

On this page