This module helps you to create groups (army) of game objects (soldiers) and organize them in several different patterns or your customized pattern and manage moving and rotating game objects as a customizable group.
The bellow git shows how DefArmy groups members and how it handles changing army pattern in real-time.
This module can easily integrate with my other extension, DefGraph. You can use DefGraph to handle movements and rotation of the entire army and then use DefArmy to handle each soldier in the army.
An example of integrating DefGraph with DefArmy, All green soldiers are in a separate army as red soldiers.
This is a community project you are welcome to contribute to it, sending PR, suggest a feature or report a bug.
You can use DefArmy in your project by adding this project as a Defold library dependency. Open your game.project file and in the dependencies field under project add:
https://github.com/dev-masih/defarmy/archive/master.zip
Once added, you must require the main Lua module via
local defarmy = require("defarmy.defarmy")
Then you can use the DefArmy functions using this module.
Official Defold game asset page for DefArmy
There are several parameters that you can assign to an army and you can change these parameters at any time.
This parameter determines the placement shape of soldiers in an army. this property is an enumeration value that can access via defarmy.PATTERN table. you can pass a custom function to create army pattern or choose one of the 5 built-in patterns. for example, in bellow images showed how each pattern will place 18 soldiers.
 |
 |
 |
|---|---|---|
| BOTTOM_TO_TOP_SQUARE | TOP_TO_BOTTOM_SQUARE | TRIANGLE |
 |
 |
|---|---|
| RHOMBUS_TALL | RHOMBUS_SHORT |
CUSTOMIZED
You can create a customized pattern, you should select defarmy.PATTERN.CUSTOMIZED as the pattern and pass a customized function to create pattern schema. This function will get a number as a parameter that is the total count of members in army and return a table that specify that each row of army pattern should have what number of soldiers in it, row count should start from the bottom of the army and ends with top. note that the sum of row values must be equal to the total count that passed to the customized pattern function. the 0 value rows will automatically remove from the table.
example:
for this pattern customize function should return a table like:{3, 5, 4, 3, 2, 1}with exactly this order.
This parameter determines is soldiers completely stick to their placements in an army or they follow their placements. this parameter mostly seen when an army is rotating.
 |
 |
|---|---|
| Sticky | Not Sticky |
These are the list of available functions to use, for better understanding of how this module works, please take a look at project examples.
defarmy.army_create(army_center_position, army_initial_rotation, member_padding, is_sticky, army_pattern, [pattern_func])
Create a group of game objects (army) with specified member padding and pattern.
- army_center_position
(vector3)- Army center position - army_initial_rotation
(quat)- Army initial rotation quat - member_padding
(number)- Padding between members - is_sticky
(boolean)- Is members glued to their places in army - army_pattern
(PATTERN)- Army pattern - pattern_func
(func)- Optional army customized pattern function[nil](see Pattern.CUSTOMIZED section)
(number)- Newly added army id
Remove a grouping of game objects (army) and release it's members.
- army_id
(number)- Army id number
Return an army members (soldiers) id.
- army_id
(number)- Army id number
(table)- List of soldier's id that were members of that army
Update an army center position.
- army_id
(number)- Army id number - army_center_position
(vector3)- New army center position
Update an army rotation.
- army_id
(number)- Army id number - army_rotation
(quat)- New army rotation quat
Update an army pattern.
- army_id
(number)- Army id number - army_pattern
(PATTERN)- New army pattern - pattern_func
(func)- Optional army customized pattern function[nil](see Pattern.CUSTOMIZED section)
Update an army stickiness.
- army_id
(number)- Army id number - is_sticky
(boolean)- Is members glued to their places in army
Create a new soldier and optionally assign it to an army.
- position
(vector3)- Soldier current position - initial_direction
(vector3)- Soldier initial direction vecotr - army_id
(optinal number)- Optional army id number[nil]
(number)- Newly added soldier id
Assign an existing soldier to a given army.
- soldier_id
(number)- Soldier id number - army_id
(number)- Army id number
Deassign a soldier from army.
- soldier_id
(number)- Soldier id number
Completely remove a soldier.
- soldier_id
(number)- Soldier id number
Calculate a soldier next postion and rotation.
- soldier_id
(number)- Soldier id number - current_position
(number)- Soldier current position - speed
(number)- Soldier speed - threshold
(optinal number)- Optional soldier placement detection threshold[1]
(vector3)- Soldier next position(quat)- Soldier next rotation
Army debugging.
- army_id
(number)- Army id number - debug_color
(vector4)- Color used for debugging
Turn on soldier position debugging.
- soldier_id
(number)- Soldier id number - debug_color
(vector4)- Color used for debugging
Turn off soldier position debugging.
- soldier_id
(number)- Soldier id number
If you really like my work and want to support me, consider donating to me with LTC, BTC or ETH. All donations are optional and are greatly appreciated. 🙏
| LTC | BTC | ETH |
|---|---|---|
 |
 |
 |
| ltc1qm6r32vjahm8wwd688enxnutks0jffc3kqg7ps5 | bc1qcuuc5r4jw38vf2eztsxag68papuwzd25chrepx | 0x02c22832bc115933Ac11388D5A91e0990eE84667 |
DefArmy is released under the MIT License. See the bundled LICENSE file for details.