单位引用：修订间差异

2026年2月25日 (三) 13:43的最新版本

单位引用（Unit References，缩写：unitref）是铁锈战争1.15新加入的单位选择器，可引用符合条件的单位。

查询

单位引用
标记	getAsMarker() getOffsetRelative() getOffsetAbsolute() createMarker()
变量引用	thisActionTarget eventSource
函数引用	attachment() transporting() nearestUnit() globalSearchForFirstUnit() self attacking lastDamagedBy parent activeWaypointTarget
存储引用	customTarget1 customTarget2
空引用	nullUnit

标记

你可立即创建一个临时标记，可用来反映位置（Position）、朝向（Direction）、高度（Height）、队伍编号（Team ID），且不需要用到时会自动销毁，不隶属任何单位也不受单位后续行为的影响。标记可分为两种，照铁锈战争的说法，一种是获取（get...），另一种是创建(create...)。获取会在以单位的基础创建标记，而创建完全与创建它的单位无关。

标记的格式（注：方括号参数为选填）

获取：getAsMarker()

相对：getOffsetRelative([x], [y], [height], [dirOffset])

绝对：getOffsetAbsolute([x], [y], [height])

创建：createMarker(x, y, [height], [teamId], [dir])

标记的用法

想直接获取当前位置等信息可以使用getAsMarker。铁锈战争为偏移提供了两种方案，一种是相对偏移，不止受单位位置、高度，还受朝向影响。通俗易懂就是你坐在一辆车上，你当然可以移动、旋转（dirOffset），但车移动、旋转你也必须移动、旋转。另一种是绝对偏移，只受单位位置、高度影响，比如单位坐标(1000, 1000)，向左偏移5个单位（995, 1000）。 创建标记是直接在地图上创建一个标记，队伍编号可由自己决定，可以注意的是创建标记的(x, y)必须要填，但铁锈战争允许省略(x=, y=)。

标记的例子

[hiddenAction_teleport]
# 传送到以该单位朝向角为基础再偏移自定义计时器数量角度的方向纵轴为十的位置。
teleportTo: getOffsetRelative( y = 10, dirOffset = self.customTimer )

[hiddenAction_strike]
# 炮弹发射到以路径点为中心最近标签为前哨的我方单位。
fireXTurretAtGround: 1
fireXTurretAtGround_withTarget: createMarker( activeWaypointTarget.x, activeWaypointTarget.y, teamId = self.teamId ).nearestUnit( withinRange = 1500, withTag = "outpost", relation = "own" )

变量引用

变量引用只能存在于行动链（Action Chain），可用也触发行动（alsoTriggerAction）或也加入队列（alsoQueueAction）将其传递下去，连续alsoTriggerAction或alsoQueueAction只允许十层，但可交替使用绕过限制，可存储在Unit类型的自定义内存或数组。当前行动目标（thisActionTarget）在不同情况下所指代的单位不同，与事件来源（eventSource）不同，后者只与自动触发事件（autoTriggerOnEvent）绑定，触发的事件不同所指代单位也不同。

thisActionIndex的用法

当前行动索引thisActionIndex能在遍历过程中同时知道每个元素的位置信息，索引（index）为其缩略形式。受重复触发（alsoTriggerActionRepeat）与提取资源为每个触发行动（takeResources_triggerActionForEach）影响。值为Int（整数）类型，从0开始，用于遍历数组。

eg:
[core]
# 定义类型为Number的数组。
@memory array: number[]
[hiddenAction_1]
# 触发行动2数组长度次（1次）。
alsoTriggerAction: 2
alsoTriggerActionRepeat: memory.array.size
[hiddenAction_2]
# 如果m.array[i]为0，则赋值在第i个元素赋0，否则减1。
setUnitMemory: array[index] = select( memory.array[index] == 0,0, memory.array[index] - 1 )

对应的情况

thisActionTarget用处
fireXTurretAtGround	指向的位置
alsoTriggerAction	与原行动的thisActionTarget相同
onShoot_triggerActions	炮塔射击的单位
takeResources_triggerActionIfAnyCollected	提取到的单位
takeResources_triggerActionForEach	与上同理
addWaypoint_triggerActionIfMatched	被添加路径点的单位（没明确指定某个单位时则为在那个位置的标记，如move等）

eventSource用处
tookDamage	攻击方
killedAnyUnit	杀死的单位
transportingNewUnit	新装载的单位
transportUnloadedOrRemovedUnit	刚卸载的单位
queuedUnitFinished	刚生产的单位
touchTargetSuccess	碰到的单位（需配合路径点）
newMessage	给这个单位发信的单位

thisActionTarget与eventSource的例子

[turret_super]
# 发射时触发行动。
onShoot_triggerActions: idol
[hiddenAction_idol]
# 当前行动目标指代击中的单位。
showMessageToAllPlayers: %{thisActionTarget}的笑容。

[hiddenAction_tookDmg]
# 事件来源指代攻击方。
autoTriggerOnEvent: tookDamage( withTag  = "APCR" )
showMessageToAllPlayers: 来自%{eventSource}的攻击！

函数引用

铁锈战争提供了一些常见情况可能用到的单位选择器，且所以节都能使用，可填入参数。

选填参数部分（注：方括号为选填参数）

附属：attachment([slot], [withTag])

运输：transporting([slot])

最近单位：nearestUnit([withinRange], [withTag], [relation], [incompleteBuildings], [withoutTag])

搜索首个单位globalSearchForFirstUnit([withTag], [relation], [incompleteBuildings])

请慎重使用默认参数。

附属

不填参数则返回行数最高的附属。

运输

不填参数则返回最近运输的单位。

最近单位

不填参数则返回范围550的单位。

搜索首个单位

不填参数则返回该地图最小id的单位。

无参数部分

这些单位引用的特点很明显，都是指向具体的某个单位。自身（self）一般情况下指向单位自己，也用于指代前面的单位引用，在涉及复杂单位引用逻辑时，请慎重使用self，请在初始化处定义个内存赋值self，选择使用存储自身的内存。攻击目标（attacking）为activeWaypointTarget为攻击时套上单位的快捷引用方式，相当于Attack类型的路径点。最后伤害源lastDamagedBy在事件来源为受击（tookDamage）时的快捷引用方式。父单位（parent）在单位自身为他人附属或乘员时可使用，unitref.hasParent( [withTag] )为其快捷方式。当前路径点（activeWaypointTarget）能够实时监控路径点情况，如果没明确指定某个单位则返回在那个位置的标记（Marker），但似乎不能获取该路径点的类型，路径点类型可详见代码addWaypoint_type。

函数引用的例子

[decal_1]
# 父单位的名为5的附属为自己则显示贴花。（注：UI世界与单位所在世界不同，请使用发送消息。）
isVisible: if parent.attachment( slot= 5 ) == self

[hiddenAction_repair]
# 在玩家创建新路径点时触发。
autoTriggerOnEvent: newWaypointGivenByPlayer
# 过滤，只允许类型为”修复“的路径点时触发，
requireConditional: if self.hasActiveWaypoint( type = "repair" )
showMessageToPlayer: 你正在治疗%{activeWaypointTarget}。

存储引用

与自定义内存相比，虽然自定义目标1customTarget1自定义目标2customTarget2与@memory x:unit（Unit类型的内存）用途相当，都可用于存储单位，但与内存不同，自定义目标在单位死亡、删除的情况下会自动清除。内存需要手动管理，而自定义目标会自动管理。内存可以用高频触发行动复现。

{{折叠|复现CustomTarget的例子|<pre>[core]# 高频，一秒六十次。autoTriggerCooldownTime: 1autoTriggerCooldownTime_allowDangerousHighCPU: true# 不推荐使用关键字命名内存。@memory customTarget1: unit[hiddenAction_update]# 高频触发检测单位是否死亡或删除。autoTrigger: if substring( str(memory.customTarget1), length(str(memory.customTarget1)) - 7, length(str(memory.customTarget1)) - 1 ) == "[dead]" or substring( str(memory.customTarget1), length(str(memory.customTarget1)) - 10, length(str(memory.customTarget1)) - 1 ) == "[deleted]"# 清空内存。setUnitMemory: customTarget1 = nullUnit</pre>}}

单位生产（canBuild)、产生(produceUnitsspawnUnit(s)）出来时，该出厂单位的自定义目标1默认为工厂。工厂不必通过queuedUnitFinished事件配合sendMessageTo告诉出厂单位谁是工厂。

空引用

单位引用中，空（null）指向不存在的单位引用。逻辑布尔值（Logic Boolean，类似条件判断）中，可搭配不等式避免返回Unit类型。自定义内存中，也可作为空值赋值，也可用于清空数组。空单位引用nullUnit与前者不同，不可用于清空数组。

@@ 第1行： / 第1行： @@
-'''单位引用'''（Unit Reference）是铁锈战争[[1.15]]新加入的单位选择器，可引用符合条件的单位。
+'''单位引用'''（Unit References，缩写：unitref）是铁锈战争[[1.15]]新加入的单位选择器，可引用符合条件的单位。
 ==查询==
@@ 第8行： / 第8行： @@
 |getAsMarker()
 getOffsetRelative()
 getOffsetAbsolute()
 createMarker()
 |-
-|局内
+|变量引用
 |thisActionTarget
 eventSource
 |-
-|全局
+|函数引用
 |attachment()
 transporting()
+nearestUnit()
+globalSearchForFirstUnit()
+self
 attacking
 lastDamagedBy
 parent
 activeWaypointTarget
-nearestUnit()
-globalSearchForFirstUnit()
 |-
-|存储
+|存储引用
 |customTarget1
 customTarget2
 |-
-|其他
+|空引用
 |nullUnit
 |}
 ==标记==
-临时、快速地创建一个标记，可用来反映位置、朝向、高度、队伍编号，且不需要用到时会自动移除，不隶属任何单位也不受单位后续行为的影响。
+你可立即创建一个临时标记，可用来反映位置（Position）、朝向（Direction）、高度（Height）、队伍编号（Team ID），且不需要用到时会自动销毁，不隶属任何单位也不受单位后续行为的影响。
 标记可分为两种，照铁锈战争的说法，一种是'''获取'''（get...），另一种是'''创建'''(create...)。获取会在以单位的基础创建标记，而'''创建'''完全与创建它的单位无关。
-===标记的格式===
+===标记的格式（注：方括号参数为选填）===
 <p>获取：<code>getAsMarker()</code></p>
 <p>相对：<code>getOffsetRelative([x], [y], [height], [dirOffset])</code></p>
@@ 第48行： / 第59行： @@
 {{折叠|标记的例子|<pre>
-teleportTo: getOffsetRelative(y= 10, dirOffset= self.customTimer)
+[hiddenAction_teleport]
+# 传送到以该单位朝向角为基础再偏移自定义计时器数量角度的方向纵轴为十的位置。
+teleportTo: getOffsetRelative( y = 10, dirOffset = self.customTimer )
-fireXTurretAtGround_withTarget: createMarker(activeWaypointTarget.x, activeWaypointTarget.y, teamId= self.teamId).nearestUnit(withinRange= 1500, withTag= "outpost", relation= "own")
+[hiddenAction_strike]
+# 炮弹发射到以路径点为中心最近标签为前哨的我方单位。
+fireXTurretAtGround: 1
+fireXTurretAtGround_withTarget: createMarker( activeWaypointTarget.x, activeWaypointTarget.y, teamId = self.teamId ).nearestUnit( withinRange = 1500, withTag = "outpost", relation = "own" )
 </pre>}}
-==局内==
+==变量引用==
-局内只能在行动内使用，可用<code>alsoTriggerAction</code>或<code>alsoQueueAction</code>延长“寿命”，你也可以用内存将其存储。<code>thisActionTarget</code>在不同情况下所指代的单位不同，与<code>eventSource</code>不同，后者只与<code>autoTriggerOnEvent</code>绑定，触发的事件不同所指代的单位也不同。
+变量引用只能存在于'''行动链'''（Action Chain），可用'''也触发行动'''（<code>alsoTriggerAction</code>）或'''也加入队列（'''<code>alsoQueueAction</code>）将其传递下去，连续<code>alsoTriggerAction</code>或<code>alsoQueueAction</code>只允许十层，但可交替使用绕过限制，可存储在<code>Unit</code>类型的[[自定义内存]]或[[数组]]。'''当前行动目标'''（<code>thisActionTarget</code>）在不同情况下所指代的单位不同，与'''事件来源'''（<code>eventSource</code>）不同，后者只与'''自动触发事件'''（<code>autoTriggerOnEvent</code>）绑定，触发的事件不同所指代单位也不同。
 ===thisActionIndex的用法===
-<code>thisActionIndex</code>能在遍历过程中同时知道每个元素的位置信息，<code>index</code>为其缩略形式。受<code>alsoTriggerActionRepeat</code>与<code>takeResources_triggerActionForEach</code>影响。
+'''当前行动索引'''<code>thisActionIndex</code>能在遍历过程中同时知道每个元素的位置信息，'''索引'''（<code>index</code>）为其缩略形式。受'''重复触发'''（<code>alsoTriggerActionRepeat</code>）与'''提取资源为每个触发行动（'''<code>takeResources_triggerActionForEach</code>）影响。值为<code>Int</code>（整数）类型，从0开始，用于遍历数组。<pre>eg:
+[core]
+# 定义类型为Number的数组。
+@memory array: number[]
+[hiddenAction_1]
+# 触发行动2数组长度次（1次）。
+alsoTriggerAction: 2
+alsoTriggerActionRepeat: memory.array.size
+[hiddenAction_2]
+# 如果m.array[i]为0，则赋值在第i个元素赋0，否则减1。
+setUnitMemory: array[index] = select( memory.array[index] == 0,0, memory.array[index] - 1 )</pre>
 ===对应的情况===
-{| class="wikitable"
+{| class="wikitable sortable mw-collapsible mw-collapsed"
 |+thisActionTarget用处
 |fireXTurretAtGround
@@ 第80行： / 第107行： @@
 |}
-{| class="wikitable"
+{| class="wikitable sortable mw-collapsible mw-collapsed"
 |+eventSource用处
 |tookDamage
-|攻击你的单位
+|攻击方
 |-
 |killedAnyUnit
@@ 第106行： / 第133行： @@
 {{折叠|thisActionTarget与eventSource的例子|<pre>
 [turret_super]
+# 发射时触发行动。
 onShoot_triggerActions: idol
 [hiddenAction_idol]
+# 当前行动目标指代击中的单位。
 showMessageToAllPlayers: %{thisActionTarget}的笑容。
 [hiddenAction_tookDmg]
-autoTriggerOnEvent: tookDamage(withTag="APCR")
+# 事件来源指代攻击方。
+autoTriggerOnEvent: tookDamage( withTag  = "APCR" )
 showMessageToAllPlayers: 来自%{eventSource}的攻击！
 </pre>}}
-==全局==
+==函数引用==
-铁锈战争提供了一些常见情况可能用到的单位选择器，且所以节都能使用，与'''局内'''相对。
+铁锈战争提供了一些常见情况可能用到的单位选择器，且所以节都能使用，可填入参数。
-===选填参数部分===
+===选填参数部分（注：方括号为选填参数）===
 <p>附属：<code>attachment([slot], [withTag])</code></p>
 <p>运输：<code>transporting([slot])</code></p>
-<p>最近单位：<code>nearestUnit([withinRange], [withTag], [relation])</code></p>
+<p>最近单位：<code>nearestUnit([withinRange], [withTag], [relation], [incompleteBuildings], [withoutTag])</code></p>
-<p>搜索首个单位<code>globalSearchForFirstUnit([withTag], [relation])</code></p>
+<p>搜索首个单位<code>globalSearchForFirstUnit([withTag], [relation], [incompleteBuildings])</code></p>
-====参数都为选填，默认情况就很有趣了。====
+===='''<big>请慎重使用默认参数。</big>'''====
 *附属
-不填参数则返回行数最高的单位。
+不填参数则返回行数最高的附属。
 *运输
 不填参数则返回最近运输的单位。
 *最近单位
-不填参数则返回范围约为500内的单位。
+不填参数则返回范围550的单位。
 *搜索首个单位
 不填参数则返回该地图最小id的单位。
 ===无参数部分===
-这些单位引用的特点很明显，都是指向具体的某个单位。
+这些单位引用的特点很明显，都是指向具体的某个单位。'''自身（<code>self</code>）'''一般情况下指向单位自己，也用于指代前面的单位引用，在涉及复杂单位引用逻辑时，请慎重使用<code>self</code>，请在初始化处定义个内存赋值'''<code>self</code>'''，选择使用存储自身的内存。'''攻击目标'''（<code>attacking</code>）为<code>activeWaypointTarget</code>为攻击时套上单位的快捷引用方式，相当于<code>Attack</code>类型的路径点。'''最后伤害源'''<code>lastDamagedBy</code>在事件来源为'''受击（'''<code>tookDamage</code>）时的快捷引用方式。'''父单位'''（<code>parent</code>）在单位自身为他人附属或乘员时可使用，<code>unitref.hasParent( [withTag] )</code>为其快捷方式。'''当前路径点'''（<code>activeWaypointTarget</code>）能够实时监控路径点情况，如果没明确指定某个单位则返回在那个位置的标记（Marker），但似乎不能获取该路径点的类型，路径点类型可[https://docs.google.com/spreadsheets/d/1aeP3pUic0IutZlgGix_cM8xR7LEH44gS4itAxETK954/htmlview 详见]代码<code>addWaypoint_type</code>。
-<code>attacking</code>为<code>activeWaypointTarget</code>为攻击时套上单位的快捷引用方式。<code>lastDamagedBy</code>在事件来源为tookDamage时的快捷引用方式。<code>parent</code>在单位自身为他人附属时可使用。<code>activeWaypointTarget</code>能够实时监控路径点情况，如果没明确指定某个单位则返回在那个位置的标记（Marker），但似乎不能获取该路径点的类型，路径点类型可[https://docs.google.com/spreadsheets/d/1aeP3pUic0IutZlgGix_cM8xR7LEH44gS4itAxETK954/htmlview 详见]代码<code>addWaypoint_type</code>。
-{{折叠|全局单位引用的例子|<pre>
+{{折叠|函数引用的例子|<pre>
-isVisible: if parent.attachment(slot= 5) == self
+[decal_1]
+# 父单位的名为5的附属为自己则显示贴花。（注：UI世界与单位所在世界不同，请使用发送消息。）
+isVisible: if parent.attachment( slot= 5 ) == self
 [hiddenAction_repair]
+# 在玩家创建新路径点时触发。
 autoTriggerOnEvent: newWaypointGivenByPlayer
-requireConditional: if self.hasActiveWaypoint(type= "repair")
+# 过滤，只允许类型为”修复“的路径点时触发，
+requireConditional: if self.hasActiveWaypoint( type = "repair" )
 showMessageToPlayer: 你正在治疗%{activeWaypointTarget}。
 </pre>}}
-==存储==
+==存储引用==
-与[[自定义内存]]相比，虽然<code>customTarget1</code>与<code>customTarget2</code>与<code>@memory x:unit</code>功能相当，但前者能实时清理使用不了的单位。
+与[[自定义内存]]相比，虽然'''自定义目标1'''<code>customTarget1</code>'''自定义目标2'''<code>customTarget2</code>与<code>@memory x:unit</code>（<code>Unit</code>类型的内存）用途相当，都可用于存储单位，但与内存不同，自定义目标在单位死亡、删除的情况下会自动清除。内存需要手动管理，而自定义目标会自动管理。
-单位生产、产生出来时，它的'''自定义目标1'''默认为工厂（把你生成出来的单位），这很有用，工厂不必通过<code>queuedUnitFinished</code>事件配合<code>sendMessageTo</code>告诉产物''把你生产出来的是谁''。
+内存可以用高频触发行动复现。
+<nowiki>{{折叠|复现CustomTarget的例子|<pre>[core]# 高频，一秒六十次。autoTriggerCooldownTime: 1autoTriggerCooldownTime_allowDangerousHighCPU: true# 不推荐使用关键字命名内存。@memory customTarget1: unit[hiddenAction_update]# 高频触发检测单位是否死亡或删除。autoTrigger: if substring( str(memory.customTarget1), length(str(memory.customTarget1)) - 7, length(str(memory.customTarget1)) - 1 ) == "[dead]" or substring( str(memory.customTarget1), length(str(memory.customTarget1)) - 10, length(str(memory.customTarget1)) - 1 ) == "[deleted]"# 清空内存。setUnitMemory: customTarget1 = nullUnit</pre>}}</nowiki>
+单位生产（<code>canBuild</code>)、产生(<code>produceUnits</code><code>spawnUnit(s)</code>）出来时，该出厂单位的'''自定义目标1'''默认为工厂。工厂不必通过<code>queuedUnitFinished</code>事件配合<code>sendMessageTo</code>告诉出厂单位谁是工厂。
-==其他==
+==空引用==
-<code>nullUnit</code>有另一种写法，也就是<code>null</code>，但后者更泛用且简略，前者更像是特指，特指'''空'''的是单位。
+单位引用中，'''空'''（<code>null</code>）指向不存在的单位引用。逻辑布尔值（<code>Logic Boolean</code>，类似条件判断）中，可搭配不等式避免返回<code>Unit</code>类型。[[自定义内存]]中，也可作为空值赋值，也可用于清空[[数组]]。'''空单位引用'''<code>nullUnit</code>与前者不同，不可用于清空数组。