选择 Mod，下次启动自动加载

鐗堟湰鏇存柊鎽樿

• v3.2锛氭鍣ㄧ毊鑲?妯″瀷鐪熷疄搴旂敤绾圭悊锛坱exture/normal/rough/metal/emissive锛屾敮鎸?URL/DataURL/Canvas/Image 涓庡唴缃浘妗?camo/stripes/dots/grid锛夛紝鏂板 loadModTexture/generatePatternTexture銆?- v3.1锛氭柊澧炲紑濮?璁剧疆/鏆傚仠鐣岄潰閫氱敤 UI 娉ㄥ唽 API銆?- v3.0锛欰PI 鐗堟湰妫€娴嬨€丩CTRL 韫蹭笅 / SHIFT 濂旇窇涓?CS2 绉诲姩鏁ｅ皠銆丄I 鎬ュ仠/韫插皠/璺抽棯/濂旇窇鎴樻湳銆?4 鎶婃灙鐙珛閰嶈壊銆?

API 版本兼容性（重要！）

模组在调用 registerMod 时必须声明 apiVersion，格式为 "主版本.次版本.补丁版本"（例如 "3.1.0"）。

版本检测规则： 主版本号必须匹配，次版本号和补丁版本号不能高于游戏当前版本。

版本不符的处理： 游戏会立刻终止其他所有脚本执行，显示全屏错误界面，提示模组名称、错误信息、游戏当前 API 版本，提供"刷新页面"按钮。

示例：

TacticalAssaultAPI.registerMod('my-mod', {
  name: '我的模组', version: '1.0.0',
  apiVersion: '3.1.0',  // 必须声明！
  author: '作者名', capabilities: ['weapon.custom', 'ui.custom']
});

API 版本检测函数：

• checkApiVersion(modApiVersion, modName)：检测模组 API 版本是否兼容
• handleIncompatibleMod(modName, error)：处理不兼容的模组

---

可制作的 Mod 类型

• 武器类：注册自定义武器、修改武器属性、自制武器皮肤
• 玩家类：修改玩家属性、自制玩家皮肤、读取玩家状态
• 地图类：自制地图、动态生成地图物体、添加/移除碰撞箱
• 游戏模式类：自制游戏模式、切换游戏模式
• 投掷物类：注册自定义投掷物
• 音效/特效类：自定义音效、粒子特效、爆炸
• AI 类：自定义 AI 行为、生成/移除敌人、获取 AI 列表
• 场景/渲染类：场景/相机/渲染器控制、天空/雾/环境光、天气/夜景
• 物理类：时间缩放、重力、碰撞检测
• UI 类：自定义 UI 元素、消息提示、Toast、准星/HUD 控制
• 联机类：联机房间、玩家列表、数据同步、聊天
• 指令类：注册自定义控制台指令
• 数据存储：localStorage 保存/加载 Mod 数据

---

能力 ID 清单（registerMod 的 capabilities 必须使用这些 ID）

capabilities 只能填写下表中的 ID，需 1–20 个，且要与 Mod 实际调用的 API 对应。local 表示仅影响本地表现，blocked 表示联机对局中不允许使用。

能力 ID	含义	联机
weapon.custom	注册/修改武器与自定义子弹（含 CS2 散射、后坐力参数）	blocked
weapon.skin	武器皮肤（颜色 + 真实纹理贴图）	local
weapon.model	自定义/替换枪械视图模型、缩放、位置偏移	local
player.stats	玩家属性与调试接口（含无敌/飞行/穿墙，启用时不计分）	blocked
player.appearance	玩家皮肤、自定义人物模型、手臂显隐	local
asset.texturepack	材质包、材质属性、纹理替换	local
asset.shaderpack	光影包、色调映射、曝光、阴影、太阳/环境光	local
movement.physics	CS2 移动/急停/散射/后坐力配置、碰撞箱、时间缩放、重力	blocked
map.custom	自制地图与动态地图物体	blocked
gamemode.custom	自制游戏模式与生命周期回调	blocked
game.mode	在内置/自定义模式间切换、暂停/恢复/结束	blocked
event.listen	只读订阅 40+ 游戏与联机事件	local
ui.custom	HUD 与开始/设置/暂停界面自定义元素、按钮、HTML	local
throwable.register	注册自定义投掷物、生成爆炸	blocked
sound.custom	自定义音效与音频合成	local
effect.custom	粒子特效、拖尾、调试绘制	local
ai.custom	自定义 AI 行为、生成/移除/配置/治疗/指定目标	blocked
team.custom	自定义队伍、队伍颜色与得分	blocked
scene.render	场景/相机/渲染器、天空/雾/天气/昼夜、场景物体	local
online	只读联机状态/玩家列表、透传消息、联机聊天（联机对局强制禁模，仅单机调试）	local

旧版本出现过的 weapon.register/weapon.modify/bullet.custom 已合并为 weapon.custom；player.skin 并入 player.appearance；map.object 并入 map.custom；ai.behavior/ai.control 并入 ai.custom；physics.collision 并入 movement.physics；online.multiplayer/online.chat 并入 online。旧 Mod 请按此表更新 capabilities。

---

事件系统

事件类型

TacticalAssaultAPI.events
// GAME_START, GAME_END, GAME_PAUSE, GAME_RESUME
// PLAYER_SPAWN, PLAYER_DAMAGE, PLAYER_KILL, PLAYER_DEATH, PLAYER_RESPAWN, PLAYER_JUMP, PLAYER_MOVE
// WEAPON_FIRE, WEAPON_RELOAD, WEAPON_SWITCH, WEAPON_EMPTY, WEAPON_HIT
// ENEMY_SPAWN, ENEMY_DEATH, ENEMY_DAMAGE, ENEMY_HEAL
// ROUND_START, ROUND_END
// MAP_LOAD, MAP_OBJECT_SPAWN, MAP_OBJECT_REMOVE
// EFFECT_SPAWN, SOUND_PLAY, TEAM_SCORE
// UPDATE, LATE_UPDATE, FIXED_UPDATE

API

• on(eventName, callback)：监听事件，返回取消函数
• once(eventName, callback)：监听一次
• off(eventName, callback)：取消监听
• emit(eventName, data)：触发自定义事件（custom: 前缀）

---

Mod 管理

• registerMod(modId, modInfo)：注册 Mod
  • modInfo: { name, version, author, description, capabilities[], dependencies[] }
• getMod(modId) / getAllMods() / isModEnabled(modId)

---

武器系统

• registerWeapon(weaponDef)：注册自定义武器
  • 属性：name, damage, fireRate, recoil, spread, bulletSpeed, color, auto, magSize, reloadTime, category, sound, reloadStyle, scopeType, moveSpreadMult, jumpSpreadMult, crouchSpreadMult, firstShotSpread, recoilVertical, recoilHorizontal, recoilRecovery
• getAllWeapons() / getWeapon(name)
• modifyWeapon(weaponName, modifications)：修改现有武器属性
• setPlayerWeapon(weaponName)：切换玩家武器
• getCurrentWeapon()：获取当前武器
• getAmmo()：获取弹药 { mag, reserve, total }
• giveAmmo(amount)：补充弹药
• reloadWeapon()：手动换弹

CS2风格移动散射系统（v2.5新增）

每把武器都有独立的散射参数：

• moveSpreadMult：移动散射倍率（速度越快散射越大）
• jumpSpreadMult：跳跃散射倍率（通常6-8倍）
• crouchSpreadMult：蹲下散射倍率（通常0.4-0.5倍）
• firstShotSpread：首发散射（第一发子弹散射更小）
• recoilVertical：垂直后坐力
• recoilHorizontal：水平后坐力
• recoilRecovery：后坐力恢复速度

散射计算优先级：跳跃 > 奔跑 > 移动 > 蹲下 > 静止

• 开镜时散射×0.35，狙击枪开镜散射归零
• 连续射击后坐力累积导致散射逐渐增加

多彩枪械配色（v2.5新增）

34把枪每把都有独特配色方案，使用金属材质（7种）、聚合物材质（10种）、木质材质（2种）。每把枪配色由WeaponMaterialLib[weaponName]定义，包含body/accent/wood/hand四个材质。

武器皮肤（v3.2修复：支持纹理贴图）

• registerWeaponSkin(skinId, skinDef)：注册皮肤
  • skinDef: { name, weapon, color, metalness, roughness, texture, normalMap, roughnessMap, metalnessMap, emissiveMap, pattern, repeat, wrap }
  • texture/normalMap/roughnessMap/metalnessMap/emissiveMap: 纹理贴图（v3.2修复，现在真正应用）
  • pattern: 内置图案 camo/stripes/dots/grid
  • repeat/wrap: 纹理重复和包裹
• applyWeaponSkin(weaponName, skinId)：应用皮肤（包含纹理贴图）
• loadModTexture(source, options)：加载纹理（URL/DataURL/Canvas/Image）
• generatePatternTexture(pattern, baseColor)：生成内置图案纹理

纹理皮肤示例：

// 注册带纹理的武器皮肤（v3.2修复，现在真正应用纹理）
TacticalAssaultAPI.registerWeaponSkin('gold-camo-ak', {
  name: '黄金迷彩AK', weapon: 'AK47',
  color: 0xffd700, metalness: 0.9, roughness: 0.2,
  texture: 'https://example.com/gold_camo.png',  // 纹理URL
  normalMap: 'https://example.com/normal.png',
  repeat: { x: 2, y: 2 }
});
TacticalAssaultAPI.applyWeaponSkin('AK47', 'gold-camo-ak');

// 使用内置图案（无需外部图片）
TacticalAssaultAPI.registerWeaponSkin('camo-m4', {
  name: '迷彩M4', weapon: 'M4A1',
  color: 0x4a6b3a, pattern: 'camo'  // 内置: camo/stripes/dots/grid
});
TacticalAssaultAPI.applyWeaponSkin('M4A1', 'camo-m4');

---

玩家系统

• setPlayerStats(stats)：修改玩家属性
  • stats: { maxHp, speed, jumpSpeed, gravity, radius, height, hp, crouchSpeedMult, sprintSpeedMult, crouchHeightMult }
• getPlayerState()：获取玩家状态
  • 返回：{ hp, maxHp, position, velocity, yaw, pitch, onGround, kills, score, team, weapon, gameState, burning, isCrouching, isSprinting }
• setPlayerPosition(x, y, z) / teleportPlayer(x, y, z)：传送
• healPlayer(amount) / damagePlayer(amount, source)：治疗/伤害
• killPlayer() / respawnPlayer()：杀死/重生
• getScore() / addScore(amount)：得分

移动系统（v2.5新增）

• 蹲下：LCTRL键，速度减半（crouchSpeedMult: 0.5），视角降低（crouchHeightMult: 0.6），射击精度提升（散射×0.5）
• 奔跑：SHIFT+W键，速度提升30%（sprintSpeedMult: 1.3），射击精度降低（散射×2.0），奔跑持枪动画
• CS2风格移动散射：
  • 静止：基础散射
  • 移动：散射×moveSpreadMult（速度越快散射越大）
  • 奔跑：散射×2.0
  • 跳跃：散射×jumpSpreadMult（通常6-8倍）
  • 蹲下：散射×crouchSpreadMult（通常0.4-0.5倍）
  • 开镜：散射×0.35，狙击枪开镜散射归零
• setCrouching(enabled)：设置蹲下状态
• setSprinting(enabled)：设置奔跑状态
• getMovementState()：获取移动状态 { isCrouching, isSprinting, isMoving, isJumping, speed }

玩家皮肤

• registerPlayerSkin(skinId, skinDef)：注册皮肤
  • skinDef: { name, bodyColor, headColor, texture, model }
• applyPlayerSkin(skinId)：应用皮肤（修改玩家和队友模型材质）
• getAllPlayerSkins()

---

游戏模式

• registerGameMode(modeId, modeDef)：注册自定义模式
  • modeDef: { name, description, maxPlayers, teamsCount, respawnEnabled, respawnTime, winCondition, targetKills, targetTime, onStart, onEnd, onUpdate, onPlayerSpawn, onPlayerDeath, onPlayerKill }
• setGameMode(mode)：切换模式（'squad'/'tdm'/'horde' 或自定义 ID）
• getGameMode(modeId) / getAllGameModes() / getActiveCustomMode()
• getGameState()：获取游戏状态 { state, mode, ended, time, customMode }
• pauseGame() / resumeGame() / endGame(win)

---

地图系统

• registerMap(mapId, mapDef)：注册地图
  • mapDef: { name, description, size, wallHeight, objects[], spawnPoints[], onLoad, onUnload }
• loadMap(mapId) / unloadMap() / getMap(mapId) / getAllMaps() / getCurrentMap()

地图物体

• spawnMapObject(objectDef)：生成物体
  • objectDef: { type('box'/'sphere'/'cylinder'/'cone'/'plane'), position, rotation, scale, color, material('basic'/'phong'/'standard'), collision, physics }
• removeMapObject(objectId) / getMapObjects()

---

投掷物与子弹

• registerThrowable(throwableDef)：注册投掷物
  • 属性：name, damage, radius, fuseTime, color
• getAllThrowables()
• spawnThrowable(type, position, velocity)：生成投掷物
• createExplosion(position, radius, damage)：创建爆炸（视觉+伤害）

子弹类型

• registerBulletType(bulletId, bulletDef)
  • 属性：damage, speed, color, size, gravity, piercing, explosive, explosionRadius
• getBulletType(bulletId) / getAllBulletTypes() / modifyBullet(bulletId, modifications)

---

AI 系统

• registerAIBehavior(behaviorId, behaviorDef)：注册 AI 行为
  • 回调：onUpdate, onSeeEnemy, onHearSound, onDamage, onDeath, onSpawn
• getAIBehavior(behaviorId) / getAllAIBehaviors()
• getAllAI() / getTeammates() / getEnemies()
• getEnemyCount()
• spawnEnemy(position, team, weaponIndex)
• removeEnemy(enemyId)

AI 高级战术行为（v2.5新增）

AI在中距离战斗状态下会自动使用以下高级战术：

• 急停射击：移动时突然停下来射击（30%概率），急停时散射×0.4（精度提升60%）
• 蹲下射击：中远距离时蹲下射击（25%概率），蹲下时散射×0.5（精度提升50%），速度减半
• 跳跃闪躲：被攻击或近距离时跳跃躲避（20%概率），跳跃时散射×3.0（精度极低）
• 奔跑接敌：距离>25米时自动奔跑，速度提升30%，散射×2.0（精度降低）

AI状态字段：

• ai._isStopping：是否急停中

• ai._isCrouching：是否蹲下中

• ai._isJumping：是否跳跃中

• ai._isSprinting：是否奔跑中

• setAITacticalEnabled(enabled)：启用/禁用AI高级战术行为

• getAIState(aiId)：获取AI状态 { isStopping, isCrouching, isJumping, isSprinting, currentWeapon, hp, team }

---

队伍系统

• registerTeam(teamDef)：注册队伍 { name, color, spawnPoints[] }
• modifyTeam(teamId, modifications)：修改 { color, name }
• getTeams() / getTeamScore(teamId) / setTeamScore(teamId, score)

---

场景与渲染

• getScene() / getCamera() / getRenderer() / getClock()
• setSkyColor(color) / setFog(color, near, far) / setAmbientLight(intensity, color)
• setWeather(type)：'clear'/'rain'/'snow'/'fog'
• getWeather()
• setNightMode(enabled) / isNightMode()

---

联机模式 v3（VibeHub SDK v3 · 房主权威 state-sync）

鏋舵瀯锛圡od 鍙渶璇诲叕鍏?API锛?鍩轰簬瀹樻柟 VibeHub SDK v3 鎴夸富鏉冨▉锛坱opology:'host'锛塒2P锛岃嚜鍔ㄤ腑缁у厹搴曪紝鏃犺嚜寤哄悗绔?WebSocket銆傛埧涓昏窇瀹屾暣娓告垙寰幆骞朵互 20Hz 骞挎挱鏉冨▉蹇収锛屾垚鍛樻湰鍦伴娴?鎻掑€硷紱灏勫嚮鍙笂浼犵浉鏈哄皠绾匡紝浼ゅ/閬尅/鍛戒腑鍏ㄩ儴鐢辨埧涓荤粨绠椼€傛埧涓婚€€鍑哄嵆瀵瑰眬缁撴潫锛屾渶澶?16 浜恒€傝繙绋嬬帺瀹剁敤浜烘満鍚屾浜哄舰妯″瀷涓庡ご椤舵樀绉版爣绛撅紝绗竴浜虹О鐪嬩笉鍒拌嚜宸辫韩浣撱€?

鍔熻兘鐗规€э紙鐜╁渚э紝Mod 涓嶅彲鏀癸級

鍏叡/绉佷汉鎴块棿銆乂ibeHub 璐﹀彿鏄电О銆佹埧涓婚€夋ā寮?鍦板浘/浜烘暟锛堚墹16锛?涓嶈冻琛ヤ汉鏈恒€佹垚鍛樿嚜閫夐槦浼嶃€乀 閿亰澶┿€乀ab 璁″垎鏉裤€?*杩涘叆浠讳綍鑱旀満瀵瑰眬鍓嶄唬鐮佸眰寮哄埗绂佺敤鍏ㄩ儴 Mod锛堟埧涓诲悓鏍凤級**锛屾槸 author-managed 涔嬩笂鐨勫弻淇濋櫓銆?

鑱旀満浜嬩欢锛堝彧璇伙級

online:connect銆乣online:disconnect銆乣online:playerjoin {id,name,team}銆乣online:playerleave {id}銆乣online:playerstate {id,pos,hp,weapon,state}銆乣online:shoot {id}銆乣online:hit {target,head}銆乣online:chat {name,text}銆乣online:gamestart锛岀敤 on/once 鐩戝惉锛屼笉鑳介樆姝㈡垨浼€犳潈濞佺粨鏋溿€?

鍏叡 API锛堝彧璇绘垨鍙楅檺鍙戦€侊級

• isOnline() / isHost()锛氭槸鍚﹀湪瀵瑰眬 / 鏄惁鎴夸富銆?- getOnlinePlayers()锛氱湡浜烘垚鍛?[{id,name,team,isHost,latency}]锛堜笉鍚?AI锛夈€?- getOnlineRoomId() / getOnlineRoomConfig()锛氭埧闂村彿 / {mode,map,maxPlayers,fillBots,listed,name}銆?- sendOnlineData(data) / onOnlineData(cb)锛氶€忎紶鍙潬鑷畾涔夋秷鎭紙瀵规柟缁?custom:online_data 鏀跺埌锛夛紝鍗曟潯 鈮?5535 瀛楄妭锛岀姝㈠埛灞忋€?- sendOnlineChat(text)锛氬彂閫佽仈鏈鸿亰澶┿€?

鑱旀満瀵瑰眬涓?Mod 宸茶寮哄埗绂佺敤锛屼笂杩?API 涓昏鐢ㄤ簬鍗曟満鎴栦綔鑰呰皟璇曪紱娈嬬暀 local 绫?Mod 涔熷彧鑳借鐘舵€侊紝鏃犳硶鏀瑰彉鎴夸富鏉冨▉缁撶畻銆?

---

物理与碰撞

• addCollisionBox(min, max, mesh) / removeCollisionBox(box)
• getCollisionBoxes() / checkCollision(position, radius)
• setTimeScale(scale) / getTimeScale()：时间缩放（慢动作/快进）
• setGravity(gravity) / getGravity()

---

音效与特效

• registerSound(soundId, soundDef)：{ freq, dur, type('sine'/'square'/'sawtooth'), volume, loop }
• playSound(soundId, options) / getSound(soundId) / getAllSounds()
• registerEffect(effectId, effectDef)：{ type, color, size, count, duration, speed, gravity }
• spawnEffect(effectId, position, options) / getEffect(effectId) / getAllEffects()

---

UI 系统

• addUIElement(element) / removeUIElement(element)
• showMessage(text, duration, options)：屏幕中央消息
• showToast(text, type)：右下角 Toast（'info'/'success'/'warning'/'error'）
• setCrosshairEnabled(enabled) / setHUDVisible(visible)

通用界面 UI API（v3.1新增）

支持在开始界面、设置界面、暂停界面添加自定义 UI 元素。

支持的界面名称：

• menu / menu-screen / start - 开始界面（选枪菜单）
• settings / settings-screen / setting - 设置界面
• pause / pause-screen / paused - 暂停界面

API 函数：

• getScreen(screenName)：获取指定界面的 DOM 元素
• getAllScreens()：获取所有界面的 DOM 元素 { menu, settings, pause }
• addScreenElement(screenName, html)：在指定界面添加 HTML 元素，返回添加的元素
• removeScreenElement(screenName, element)：从指定界面移除元素
• addScreenButton(screenName, text, onClick, style)：在指定界面添加按钮，返回按钮元素
• addScreenHTML(screenName, html, position)：在指定界面添加 HTML，position 可选 'prepend'/'start'/'top' 或数字索引
• clearScreenModElements(screenName)：清除指定界面的所有 Mod 添加的元素

示例：

// 在开始界面添加按钮
TacticalAssaultAPI.addScreenButton('menu', '模组按钮', () => {
  TacticalAssaultAPI.showToast('点击成功！', 'success');
}, 'margin-top:20px;background:linear-gradient(90deg,#ff6b35,#ffd93d);color:#000;');

// 在设置界面添加HTML
TacticalAssaultAPI.addScreenHTML('settings', '<div style="padding:16px;background:rgba(255,217,61,0.1);border-radius:8px;"><h3 style="color:#ffd93d;">模组设置</h3></div>');

// 在暂停界面添加元素
TacticalAssaultAPI.addScreenElement('pause', '<div style="padding:12px;color:#66aaff;">模组已启用</div>');

开始界面 UI API（旧版，仍可用）

• getMenuScreen()：获取开始界面 DOM
• addMenuElement(html) / removeMenuElement(element)
• setMenuTitle(title) / setMenuSubtitle(subtitle)
• addMenuButton(text, onClick, style)

---

控制台指令

• registerCommand(command, callback, description)：注册自定义指令
  • callback 接收参数数组
• unregisterCommand(command) / getRegisteredCommands()
• executeCommand(command)：执行指令

示例：

TacticalAssaultAPI.registerCommand('heal', (args) => {
  TacticalAssaultAPI.healPlayer(100);
  TacticalAssaultAPI.showMessage('已治疗 100 点');
}, '治疗玩家 100 点生命');

---

配置与数据

• getConfig()：获取游戏配置副本
• modifyConfig(path, value)：修改配置（如 'player.speed'）
• saveData(key, value) / loadData(key, defaultValue) / deleteData(key)：localStorage

---

性能与工具

• getFrameRate() / getDeltaTime() / getElapsedTime()
• log(message, level)：输出到游戏日志

---

计时器 API

• setTimeout(callback, ms)：设置超时（自动错误捕获）
• setInterval(callback, ms)：设置间隔（自动错误捕获）
• clearTimeout(id) / clearInterval(id)：清除计时器
• clearAllTimers()：清除所有 Mod 计时器

示例：

// 5秒后治疗玩家
TacticalAssaultAPI.setTimeout(() => {
  TacticalAssaultAPI.healPlayer(50);
}, 5000);

// 每秒增加1分
const id = TacticalAssaultAPI.setInterval(() => {
  TacticalAssaultAPI.addScore(1);
}, 1000);

---

输入系统 API

• isKeyPressed(keyCode)：检测按键是否按下（如 'KeyW', 'Space'）
• getMousePosition()：获取鼠标位置 { x, y }
• isMouseDown(button)：检测鼠标按键（0=左键，2=右键）
• lockPointer()：锁定鼠标指针
• unlockPointer()：解锁鼠标指针

---

摄像机控制 API

• setCameraPosition(x, y, z)：设置摄像机位置
• setCameraRotation(yaw, pitch)：设置摄像机旋转
• setCameraFOV(fov)：设置视野角度
• getCameraForward()：获取摄像机前方向量 { x, y, z }

---

玩家增强控制 API

• setPlayerSpeed(speed) / getPlayerSpeed()：设置/获取移动速度
• setPlayerJumpSpeed(speed)：设置跳跃速度
• setGodMode(enabled) / isGodMode()：无敌模式
• setInfiniteAmmo(enabled)：无限弹药
• setPlayerTeam(team) / getPlayerTeam()：设置/获取队伍
• setPlayerMaxHp(maxHp) / getPlayerMaxHp()：设置/获取最大血量

---

武器增强 API

• getWeaponList()：获取所有武器列表
• setWeaponAmmo(weaponName, magAmmo, reserveAmmo)：设置武器弹药
• getWeaponAmmo(weaponName)：获取武器弹药
• giveWeapon(weaponName, slot)：给予武器（slot=1或2）

---

数学工具 API

• vec3(x, y, z)：创建三维向量
• vecAdd(a, b) / vecSub(a, b) / vecScale(v, s)：向量运算
• vecLength(v) / vecNormalize(v)：向量长度/归一化
• vecDot(a, b) / vecCross(a, b)：点积/叉积
• degToRad(deg) / radToDeg(rad)：角度转换
• angleToYaw(angle) / yawToAngle(yaw)：游戏角度转换

---

颜色工具 API

• hexToRgb(hex)：十六进制转RGB
• rgbToHex(r, g, b)：RGB转十六进制
• hslToRgb(h, s, l)：HSL转RGB

---

调试绘制 API

• drawDebugLine(start, end, color, duration)：绘制调试线段
• drawDebugSphere(position, radius, color, duration)：绘制调试球体
• clearDebugObjects()：清除所有调试对象

示例：

// 在玩家位置绘制红色球体，持续5秒
TacticalAssaultAPI.drawDebugSphere(
  TacticalAssaultAPI.getPlayerState().pos,
  1.0, 0xff0000, 5000
);

---

世界与环境 API

• setSunPosition(x, y, z)：设置太阳位置
• setSunIntensity(intensity)：设置太阳强度
• setSunColor(color)：设置太阳颜色
• setAmbientIntensity(intensity)：设置环境光强度
• getWorldObjects()：获取场景物体数量

---

数据导出/导入 API

• exportGameState()：导出当前游戏状态（JSON）
• importGameState(state)：导入游戏状态
• random(min, max) / randomInt(min, max) / clamp(value, min, max) / lerp(a, b, t) / distance(pos1, pos2)

---

最小可运行 Mod

(function() {
  // 1. 注册 Mod（必须声明 apiVersion！）
  TacticalAssaultAPI.registerMod('my-first-mod', {
    name: '我的第一个 Mod',
    version: '1.0.0',
    apiVersion: '3.0.0',  // 必须声明！版本不符会终止脚本
    author: '你的名字',
    description: '示例 Mod',
    capabilities: ['weapon.custom', 'event.listen', 'ui.custom']
  });

  // 2. 注册自定义武器
  TacticalAssaultAPI.registerWeapon({
    name: '黄金AK',
    damage: 45, fireRate: 100, recoil: 0.07,
    magSize: 40, reloadTime: 1.8, color: 0xffd700,
    auto: true, category: 'rifle',
    // CS2风格散射参数
    moveSpreadMult: 1.5, jumpSpreadMult: 6.0, crouchSpreadMult: 0.5,
    firstShotSpread: 0.01, recoilVertical: 0.02, recoilHorizontal: 0.01, recoilRecovery: 0.95
  });

  // 3. 监听事件
  TacticalAssaultAPI.on('player:kill', (data) => {
    TacticalAssaultAPI.showToast('击杀！', 'success');
  });

  // 4. 注册自定义指令
  TacticalAssaultAPI.registerCommand('god', () => {
    TacticalAssaultAPI.setPlayerStats({ maxHp: 999, hp: 999 });
    TacticalAssaultAPI.showMessage('无敌模式开启');
  }, '无敌模式');

  console.log('我的第一个 Mod 已加载');
})();

---

API 接口总览（260+ 个）

游戏提供 260+ 个 API 接口，涵盖：核心系统、游戏内容、视听效果、AI与联机、高级功能、工具函数、CS2机制、API版本检测、通用界面UI、纹理加载。

版本：v3.2.0

---

加载阶段

• 启动前（beforeStart）：注册武器、地图、游戏模式、皮肤、AI 行为、指令
• 启动后（afterStart）：生成物体、应用皮肤、修改运行时状态、监听事件

---

多 Mod 规则

• Mod ID 全局唯一，使用小写字母、数字、点、横线、下划线
• 后注册的 Mod 覆盖同名注册（武器/地图/模式）
• 事件监听器按注册顺序执行，无法阻止事件
• 依赖 Mod 需在 dependencies 中声明，确保加载顺序

---

版本兼容

• API 版本遵循语义化版本（MAJOR.MINOR.PATCH）
• MINOR 版本新增功能，不破坏现有 API
• MAJOR 版本可能破坏兼容性
• 当前版本：3.2.0

---

联机策略（author-managed + 代码层强制禁模）

本游戏在 VibeHub 侧声明为 author-managed 联机策略，并在游戏代码层再加一道强制保险：

• 游戏根据每个 Mod 的 capabilities 字段判断联机兼容性：multiplayer:"local"（皮肤、UI、音效等纯本地表现）理论可保留，multiplayer:"blocked"（武器、数值、模式、物理等）联机禁用。
• 但当前版本在创建/加入/开始任何联机对局前，会强制拒绝一切已启用 Mod（房主同样不能开启），从代码层保证联机绝对公平；getEnabledMods() 非空时直接拦截并提示。
• 联机采用房主权威 state-sync：位置、伤害、AI、胜负全部由房主结算，成员端 Mod 无法伪造权威结果。
• 能力声明不是安全沙箱，Mod 代码仍在本地执行，玩家应自行判断 Mod 可信度；平台不会扫描或阻止越权代码，上述约束是作者与 Mod 创作者之间的开发约定。

---

禁止的能力

• 访问账号凭据、Token、管理接口
• 修改游戏核心网络同步逻辑
• 修改游戏核心渲染管线或物理引擎
• 访问或修改其他 Mod 的私有数据
• 频繁刷屏或显示不当内容
• 生成超出地图边界的物体
• 在游戏进行中强制切换模式
• 绕过联机 Mod 禁用机制