WarriorJS 安装指南：通过 npm 全局安装 CLI 并创建你的第一个战士

• 教育
• CLI

本篇技术指南讲解 WarriorJS（一款在 JavaScript/TypeScript 中编写 AI 战士闯塔的开源游戏）的完整安装与首次启动流程：从 Node.js 环境准备、全局安装@warriorjs/cli，到运行warriorjs命令创建战士档案、选择 "The Narrow Path" 高塔并理解生成的目录结构。读完本文，你将能够在本机快速跑起 WarriorJS、读懂Player.js与README.md的职责，并掌握 CLI 的常用参数与关卡工作流。

安装前的环境准备：Node.js 运行时

WarriorJS 的 CLI 是一个纯 Node.js 应用，因此在安装前需要确认计算机上已具备可用的 Node.js 环境。安装文档明确指出，运行npm命令前必须先安装 Node.js，推荐使用官方安装器完成安装。

需要特别说明的是版本要求：早期版本文档要求 Node.js >= 8，而当前仓库的实际版本要求更高——apps/cli/package.json 与根目录 package.json 的engines字段均声明"node": ">=24"，因此建议使用 Node.js 24 及以上版本运行本仓库对应的 CLI 版本（当前为0.14.0），以免因版本过低导致安装或启动失败。

全局安装 WarriorJS CLI

打开终端，执行以下命令将 WarriorJS 命令行工具安装到全局：

npm install --global @warriorjs/cli

npm install --global（可简写为npm i -g）会把 CLI 可执行文件链接到系统全局bin目录。从源码看，这个可执行入口定义在 apps/cli/package.json 的bin字段中：

"bin": { "warriorjs": "./bin/warriorjs.js" }

即安装完成后，系统会提供名为warriorjs的命令，实际入口脚本为 apps/cli/bin/warriorjs.js。安装过程中 npm 会自动解析并安装其全部依赖，其中包括游戏核心逻辑@warriorjs/core、能力体系@warriorjs/abilities、计分模块@warriorjs/scoring，以及内置高塔@warriorjs/tower-the-narrow-path（详见 apps/cli/package.json 的dependencies字段）。

首次运行：创建战士档案并选择高塔

安装完成后，在任意目录的终端中直接运行：

warriorjs

CLI 的入口逻辑位于 apps/cli/src/cli.ts：它会先解析命令行参数，构造Game实例与游戏上下文，再渲染交互式 UI 等待玩家操作。首次运行（当前目录下尚无档案）时，游戏会引导你完成两步初始化：

1. 给战士起一个合适的名字（如aldric）；
2. 选择 "The Narrow Path" 高塔。

The Narrow Path 是 WarriorJS 内置的入门高塔，共 9 个关卡，每一层引入一个新能力（行走、战斗、休息、营救、转身、射击等），并引导你与之前学到的能力组合使用。正如 towers/the-narrow-path/README.md 所描述的，它是一条 "只有向前、没有退路" 的狭窄走廊，是绝大多数玩家的第一站。该高塔已随@warriorjs/cli内置，无需单独安装。

生成的文件结构详解

完成上述初始化后，当前目录下会出现如下文件结构：

warriorjs └── aldric-the-narrow-path ├── Player.js └── README.md

各部分的职责如下：

• aldric-the-narrow-path：你的战士档案（profile）目录。目录名由战士名-高塔id拼接而成——从 apps/cli/src/Game.ts 的createProfile方法可以看到，实际规则是${warriorName}-${tower.id}转小写后，将非字母数字字符替换为连字符；
• Player.js：你战士的"大脑"，也就是每回合 AI 决策逻辑所在，后续会经常编辑这个文件；
• README.md：当前关卡的指令说明，包含关卡目标、能力列表与提示。

除了文档列出的两个文件，实际生成的档案目录中还会包含一个隐藏的.profile文件。从 apps/cli/src/Profile.ts 的实现可知，它是一个 Base64 编码的 JSON 文件，保存了战士名、所选高塔、语言（JavaScript/TypeScript）、当前关卡编号、得分、是否开启 Epic 模式等全部进度数据（见encode/decode方法）。因此：

• 只要.profile与Player.js/Player.ts同时存在，该目录就会被识别为一个合法档案（见isProfileDirectory方法）；
• 想换一台机器继续游戏，直接拷贝整个档案目录即可；
• 不要随意编辑或删除.profile，否则可能导致档案损坏或无法加载（Profile.load会抛出 "Corrupted .profile file" 之类的错误）。

打开 README.md 开始第一关

现在打开档案目录下的README.md，它就是第一关的完整任务书。这份文件由游戏自动生成，渲染逻辑位于 apps/cli/src/utils/renderReadme.ts，主要包含以下板块：

• 关卡信息：Level N标题、关卡描述与TIP提示；
• Floor Map：本层地图的字符画，用不同符号标出楼梯、墙壁、敌人与俘虏的位置；
• Abilities：当前关卡可用的能力清单，其中Actions（每回合只能执行一个）如warrior.walk()、warrior.attack()，以及Senses（感知类）如warrior.feel()、warrior.look()；
• Next Steps：下一步操作指引——编辑Player.js后再次运行warriorjs进入实战。

如果遇到困难，还可以在游戏内申请提示（CLUE），提示文本也会被渲染进README.md（见renderClue方法）。

编写你的第一个 AI：Player.js 模板

首次进入第一关时，游戏会自动生成Player.js骨架。模板内容来自 apps/cli/src/utils/renderPlayerCode.ts：

class Player { playTurn(warrior) { // Decide what your warrior should do. } } export default Player;

你需要做的，就是在playTurn(warrior)方法中根据warrior对象提供的感觉信息（如warrior.feel()）做出决策并调用动作能力（如warrior.walk()、warrior.attack()）。游戏的核心运行循环（每回合收集输入、执行玩家代码、推进单位行动）由 libs/core/src/runLevel.ts 驱动，能力的具体实现可参考 libs/abilities/src 下的各能力模块。

值得一提的细节：如果你在创建档案时选择 TypeScript，游戏会生成Player.ts与types.ts（类型声明），并生成带import type { Warrior } from './types.js'的模板，相关逻辑见 apps/cli/src/ProfileGenerator.ts 的generateTypesFile方法。

完成编辑后的标准循环：再次运行 warriorjs

README.md的 "Next Steps" 会告诉你：编辑完Player.js后，再次运行warriorjs命令即可用新代码挑战当前关卡。这是 WarriorJS 的核心交互循环：

# 编辑 Player.js 后，反复运行 warriorjs

每一轮关卡结束后，游戏会结算得分与评级（计分逻辑位于 libs/scoring/src，如getLevelScore、getGradeLetter），并自动为下一关重新生成README.md与所需的档案文件（见 apps/cli/src/Game.ts 的prepareNextLevel与generateProfileFiles方法）。

CLI 进阶参数

除直接运行外，warriorjs命令还支持若干命令行参数，定义在 apps/cli/src/parseArgs.ts：

例如，在非当前目录下继续游戏，或静默运行以专注于输出：

warriorjs --directory ~/games warriorjs --silent

更多高塔与后续学习

warriorjs启动时会自动发现可用高塔：内置的@warriorjs/tower-the-narrow-path无需安装即可使用；此外，官方发布的其他@warriorjs/tower-*包以及社区贡献的warriorjs-tower-*包也会被自动扫描加载（见 apps/cli/src/loadTowers.ts）。想要尝试更多高塔，可参考 docs/player/towers.md。

安装与启动只是开始。完成第一关后，建议继续阅读仓库内配套的玩家文档深入学习：

• docs/player/gameplay.md：游戏玩法与回合机制
• docs/player/options.md：CLI 与游戏选项的完整说明
• docs/player/abilities.md 与 docs/player/units.md：能力与单位的详细参考

记住核心工作流：warriorjs生成任务书 → 编辑Player.js→ 再次运行warriorjs验证。你的战士能否攻破 9 层高塔，完全取决于你写在playTurn里的每一个决策。

• 教育
• CLI