武器系统模块

脚本入口： eve.Weapon()

Weapon 提供数据驱动的武器定义、弹匣/储备弹药、射击模式、扩散与后坐力、装填、载具挂点和角色持握 Rig。武器、挂点、Rig 与弹药池都是 ECS 实体；脚本可用 eve.view(eve.WeaponEntity) 查询，但创建和状态变更应通过模块 API 完成。

注册并使用武器

local weapon = eve.Weapon();
weapon.registerWeaponsFromJson(@"[
  {""id"":""rifle"", ""logic"":""hitscan"", ""damage"":18,
   ""range"":120, ""cooldown"":0.12,
   ""ammo"":{""mag"":30,""reserve"":90,""reload"":1.8}}
]");
local rifle = weapon.newWeapon("rifle");
weapon.setAim(rifle, 15.0, -2.0);
if (weapon.canFire(rifle)) weapon.fireAt(rifle, 10.0, 0.0, 30.0, 1001);
weapon.update(dt);

注册函数返回的状态必须检查；未知 definition 会令 newWeapon 返回 null。 fireAt/attack 只生成武器域的射击结果和事件，实际命中、生命值扣除及表现由消费系统负责。每帧以模拟 dt 调用一次 update(dt)，以推进冷却和装填。

弹药池与挂点

local pool = weapon.newAmmoPool("rifle", 180);
weapon.bindAmmoPool(rifle, pool);
local turret = weapon.newMount("turret");
weapon.mountSetLimits(turret, -120.0, 120.0, -10.0, 45.0, 90.0, 60.0);
weapon.mountAttachWeapon(turret, rifle);
weapon.mountAimAt(turret, 35.0, 5.0);

共享弹药池的数量是权威值，解绑不会复制弹药。mountDestroy 后挂点引用只可用于判断销毁状态，不应继续瞄准或换装。

API 快查

定义、创建与更新

API	说明
`registerWeaponsFromJson(json)` / `clearWeaponDefinitions()`	注册或清除武器定义；不要在仍有实例时热清除定义。
`getWeaponDefinitionCount()` / `hasWeaponDefinition(id)`	查询 definition catalogue。
`getWeaponDefinitionLogic(id)` / `getWeaponDefinitionDamage(id)` / `getWeaponDefinitionRange(id)`	查询定义的逻辑、基础伤害和射程。
`getLogicCount()`	当前注册的原生 WeaponLogic 数量。
`newWeapon(defId)` / `newMount(type)` / `newRig(wield)`	创建 ECS 武器、挂点或持握 Rig。
`update(dt)`	推进所有武器的冷却、装填和状态阶段。

武器、瞄准和射击

API	说明
`getId()` / `getDefId()` / `getOwnerId()` / `setOwnerId()`	武器实体身份和逻辑 owner。
`getMagAmmo()` / `getReserveAmmo()` / `getResourceValue()`	当前弹匣、储备或通用资源值。
`getSpread()` / `getRecoilPitch()` / `getRecoilYaw()`	当前扩散与累计后坐力。
`getFireMode()` / `setFireMode()`	查询或切换射击模式。
`getSelectableModeCount()` / `getSelectableMode(i)`	枚举定义允许玩家选择的模式。
`isAiming()` / `setAiming()` / `getZoomFov()`	瞄准状态与建议 FOV。
`setAim(yaw,pitch)` / `getYaw()` / `getPitch()`	设置或查询武器瞄准角（度）。
`canFire()` / `fireAt(x,y,z,shooterId)` / `attack(yaw,pitch,shooterId)`	检查并发起射击。
`startReload()` / `cancelReload()` / `isReloading()`	控制和查询装填。
`getCooldown()` / `getStage()`	查询冷却秒数和当前逻辑阶段。

上述同名方法既可能出现在 Weapon 模块，也可能出现在 WeaponEntity 上；优先使用实体方法做单对象操作，批处理和定义管理使用模块方法。

弹药、挂点和 Rig

API	说明
`newAmmoPool(ammoType,count)` / `getAmmoType()` / `getCount()` / `setCount()`	创建和操作共享弹药池。
`addAmmo(n)` / `ammoPoolAdd(pool,n)` / `ammoPoolGetCount(pool)`	增加或读取弹药。数量不会低于零。
`bindAmmoPool()` / `unbindAmmoPool()` / `getAmmoPool()`	连接、断开或查询武器的共享弹药池。
`mountAttachWeapon()` / `mountGetWeapon()` / `mountSetLimits()`	挂载武器并设置 yaw/pitch/转速限制。
`mountAimAt()` / `aimAt()` / `mountDestroy()` / `destroy()` / `isDestroyed()`	瞄准或销毁挂点。
`getType()` / `getNodePath()` / `setNodePath()` / `getWeapon()`	查询挂点/Rig 的类型、场景节点和武器。
`newRig()` / `rigAttachWeapon()` / `rigGetWeapon()` / `rigSetPose()`	创建并操作持握 Rig。
`getWield()` / `attachWeapon()` / `setPose()`	Rig 实例的持握类型、武器和局部 pose。

事件

API	说明
`getEventCount()` / `getEventType(i)` / `clearEvents()`	枚举并清空本帧武器事件。
`getEventWeaponId()` / `getEventDefId()` / `getEventMountId()`	事件关联身份。
`getEventAmmoLeft()` / `getEventArc()` / `getEventAoe()`	事件资源和范围参数。
`getEventSpread()` / `getEventPellets()`	本次射击的扩散与弹丸数。
`getEventRecoilPitch()` / `getEventRecoilYaw()`	本次射击后坐力。
`getEventDamageType()` / `getEventElement()`	伤害分类和元素标签。

事件索引只在下一次结构修改或 clearEvents() 前有效。建议 update 后统一消费，再清空。

生命周期与确定性

定义先注册、实例后创建；热重载定义时应在安全点重建依赖的实例。
所有角度使用度，时间参数使用秒；回放需注入相同 dt 和相同射击输入序列。
ECS view 中不要创建/销毁武器或挂点，先收集 ID，遍历结束后再做结构修改。
Weapon 不拥有伤害目标；用事件把射击结果交给 combat/vehicle 等权威 owner。

5.4 KiB Raw Blame History