Strategic helpers¶
These constructors provide advanced helpers for resource searches, villager selection, and building placement. Their behavior can change between releases. Keep their use in small functions and check every result.
local resources = ResourceTracker()
local villagers = VillagerOccupation()
local placement = ConstructionPlacement()
Each constructor also has a .new() form. Call helper methods with :.
ResourceTracker¶
ResourceTracker finds resources near the assigned player and current world.
Update() currently has no result. Query methods return dense Object arrays
unless the table says otherwise.
| Method | Default values | Result |
|---|---|---|
GetConvertibleLivestock(position, radius) |
None | Nearby convertible livestock. |
GetOwnedLivestock() |
None | Assigned-player livestock. |
GetDeadLivestock(position, radius) |
None | Nearby dead livestock with food. |
GetHuntablesNear(position[, radius[, limit]]) |
48, 16 |
Nearby live huntables. |
GetBoarsNear(position[, radius[, limit]]) |
40, 4 |
Nearby boar targets. |
GetPreyNear(position[, radius[, limit]]) |
48, 16 |
Nearby prey animals. |
GetDeadHuntablesNear(position[, radius[, limit]]) |
18, 16 |
Nearby dead huntables with food. |
GetForage() |
None | Recognized forage objects. |
GetFarms() |
None | Assigned-player farms. |
GetTrees() |
None | Known trees. |
GetGold() |
None | Recognized gold objects. |
GetStone() |
None | Recognized stone objects. |
GetTreesNear(position[, radius[, limit]]) |
64, 128 |
Nearby trees. |
GetForageNear(position[, radius[, limit]]) |
64, 128 |
Nearby forage. |
GetForageDiagnosticsNear(position[, radius[, limit]]) |
64, 128 |
Nearby forage candidates. |
GetGoldNear(position[, radius[, limit]]) |
64, 128 |
Nearby gold. |
GetStoneNear(position[, radius[, limit]]) |
64, 128 |
Nearby stone. |
GetTreesNearAnchors(anchors[, radius[, limit]]) |
64, 128 |
Trees near anchors. |
GetGoldNearAnchors(anchors[, radius[, limit]]) |
64, 128 |
Gold near anchors. |
GetStoneNearAnchors(anchors[, radius[, limit]]) |
64, 128 |
Stone near anchors. |
GetForageSourceCounts() |
None | Troubleshooting count table. |
GetFoodCandidates(position, config) |
See below. | Grouped food table, or nil, reason when the assigned player or world census is unavailable. |
A near query needs a non-negative radius and limit. A limit of 0 does not
truncate the result. Standard near queries sort results by distance.
Food candidates¶
GetFoodCandidates(position, config) needs a config table. Missing fields use
these defaults:
| Field | Default |
|---|---|
deadLivestockRadius |
18 |
convertibleRadius |
32 |
forageRadius |
56 |
forageLimit |
32 |
deadHuntRadius |
32 |
deadHuntLimit |
16 |
huntRadius |
32 |
huntLimit |
16 |
The result contains deadLivestock, ownedLivestock, convertibleLivestock,
forage, deadHuntables, and huntables arrays.
An available census with no matches returns six empty arrays. An unavailable
assigned player, invalid world list/count, or world-enumeration access fault
returns nil, reason; partial enumeration is discarded. This availability result
covers the outer census. Existing per-object classifiers and position reads can
still skip objects they cannot read. The managed runner reports a failed selected
batch instead of retrying legacy scans and treating their results as zero food.
VillagerOccupation¶
VillagerOccupation selects and tracks assigned-player villagers.
| Method | Result | Meaning |
|---|---|---|
Update() |
No value | Refresh tracked villagers. |
GetVillagerCount([profession]) |
Integer | Count all villagers or one profession. |
GetIdleVillagerCount() |
Integer | Count idle, unassigned villagers. |
GetAllVillagers() |
Object array | Get tracked live villagers. |
GetIdleVillagers() |
Object array | Get idle, unassigned villagers. |
RequestVillagers(count, position[, urgency = 1]) |
Object array | Select and mark nearby candidates. |
SetPriorities(wood, food, gold, stone) |
No value | Set non-negative resource weights. |
GetPriorityPercentage(profession) |
Number | Get a current priority fraction. |
ResetPriorities() |
No value | Restore equal fractions. |
SetPriorityPercentage(profession, fraction) |
No value | Set one fraction in 0..1. |
SetLivestockVillagerLimit(value) |
No value | Set a non-negative limit. |
SetForageVillagerLimit(value) |
No value | Set a non-negative limit. |
SetFarmMaxTownCenterDistance(value) |
No value | Set a non-negative distance. |
SetFarmMaxMillDistance(value) |
No value | Set a non-negative distance. |
SetProfessionBuildingRange(profession, value) |
No value | Set a non-negative range. |
AssignVillagers(objectsOrIds) |
No value | Mark one object, ID, or dense array. |
AssignVillager(objectOrId) |
No value | Alias for AssignVillagers. |
RequestVillagers uses UrgencyLevel.LOW (0) for idle villagers,
MEDIUM (1) for idle then unassigned villagers, and HIGH (2) for all
tracked villagers.
ConstructionPlacement¶
ConstructionPlacement finds locations and can submit building requests.
| Method | Result | Meaning |
|---|---|---|
Update() |
No value | Refresh helper state. |
SetTownCenterPadding(value) |
No value | Set non-negative padding. |
FindBestPosition(structureType, target[, direction[, padding]]) |
Vector3 or nil |
Find a placement position. |
GetFootprint(structureType) |
{ width, height } or nil |
Get a known footprint. |
GetLastFailureReason() |
String | Explain the latest failed search. |
GetValidFarmPlacementTile() |
MapTile or nil |
Find a farm placement tile. |
BuildStructure(structureType[, builderId], target[, direction[, padding]]) |
Boolean | Find and submit one build request. |
BuildStructureAtTown(structureType[, target[, padding]]) |
Boolean | Build near a town-center or villager anchor. |
QueueBuildingRequest(structureType, target[, priority[, padding[, bypass[, builderId[, requireScouting]]]]]) |
No value | Add a placement request. |
QueueBuildingRequestAtTown(structureType[, priority[, padding[, bypass[, builderId[, requireScouting]]]]]) |
No value | Add a town placement request. |
ProcessBuildingRequests() |
No value | Attempt queued requests by priority. |
IsStructureTypeQueued(structureType) |
Boolean | Check the request queue. |
IsUnitAssignedToBuilding(objectOrId) |
Boolean | Check an assigned builder. |
direction accepts a PlacementDirection value or a position table. A position
table sets the direction from target toward that position.
The helper needs a known footprint and readable map data. Call
GetLastFailureReason() after a nil or false placement result.