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- Pick a release from dev-masih/defarmy releases and add its Source code (zip) URL (or a packaged
.zipasset, if the library ships one) togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as defarmy from "defarmy.defarmy"
- Pick a release from dev-masih/defarmy releases and add its Source code (zip) URL (or a packaged
Functions
army_create(army_center_position:Vector3, army_initial_rotation:Quaternion, member_padding: number, is_sticky: boolean, army_pattern:Hash, pattern_func?:PatternFunc): numberarmy_members(army_id: number): number[]army_remove(army_id: number)army_update_position(army_id: number, army_center_position:Vector3)army_update_rotation(army_id: number, army_rotation:Quaternion)army_update_pattern(army_id: number, army_pattern:Hash, pattern_func?:PatternFunc)army_update_stickiness(army_id: number, is_sticky: boolean)army_debug_draw(army_id: number, debug_color:Vector4)soldier_create(position:Vector3, initial_direction:Vector3, army_id?: number): numbersoldier_join_army(soldier_id: number, army_id: number)soldier_leave_army(soldier_id: number)soldier_remove(soldier_id: number)soldier_debug_on(soldier_id: number, debug_color:Vector4)soldier_debug_off(soldier_id: number)soldier_move(soldier_id: number, current_position:Vector3, speed: number, threshold?: number): LuaMultiReturn<[Vector3,Quaternion] | [ undefined, undefined ]>
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 ofPATTERN.pattern_func?:PatternFunc— Builds the rows forPATTERN.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 ofPATTERN.pattern_func?:PatternFunc— Builds the rows forPATTERN.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 rotationsoldier_movereturns 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 to1.
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.