Jedi-Academy是经典射击游戏《星球大战 绝地武士：绝地学院》（Star Wars Jedi Knight: Jedi Academy）由 Activision 与 Raven 官方开源的完整源码。本文带你拆解其中最核心的游戏实体系统：一个名为gentity_t的巨型结构体，配合一组Spawn变量解析机制，如何在地图加载时把枯燥的文本定义变成会移动、会战斗、会开门的立体游戏世界。即使你是第一次接触游戏引擎源码，也能读懂这条"实体诞生流水线"。

从地图文本到游戏世界：实体生成的完整流程 🎮

在 Jedi Academy 中，每一张关卡（map）都包含一段"实体定义字符串"。地图编辑器里摆放的每一个物件——一扇门、一个敌人出生点、一个触发区域——都会被写成如下风格的键值对文本：

• classname：实体类型，如func_door
• origin：三维坐标
• angle：朝向角度
• health：耐久度（可选）

服务器启动关卡时，入口函数G_SpawnEntitiesFromString会循环解析这段文本，为每一组键值对创建一个gentity_t实例。整个流程可以概括为四步：

1. 解析：G_ParseSpawnVars逐条读取key "value"键值对
2. 分配：G_Spawn从实体池g_entities[]中取出一个空闲槽位并清零
3. 填充：G_ParseField依据fields[]映射表，把键值对写进结构体对应偏移
4. 激活：G_CallSpawn根据classname查表，调用对应的SP_xxx初始化函数

核心实现位于 G_SpawnGEntityFromSpawnVars，它正是"分配→填充→激活"三步的汇总点。

gentity_t：一个结构体撑起整个世界

所有实体——玩家、敌人、武器、门、特效——共享同一个结构体定义，它声明在 struct gentity_s。这个结构体非常庞大，按功能分区组织：

一个巧妙的设计是：g_public.h 中的精简版 只保留服务器与客户端必须共享的前缀字段（位置、包围盒、Ghoul2 标记），而 g_shared.h 中的完整版 明确注释"此行之上不可改动，服务器期望字段按此顺序排列"。这种"前缀共享"设计让网络同步和存档逻辑得以精确控制内存拷贝边界。

实体并非动态申请的零散对象，而是集中存放在一个固定数组池中。g_entities池在 g_main.cpp 中定义并在 服务器初始化时整体清零，G_Spawn则负责从池中回收空闲槽位，其实现见 G_Spawn。源码注释里还保留了一个有趣的策略：刚释放的实体槽位要"冷却"1秒再复用，避免客户端把"死亡重生"误渲染成"变形"。

Spawn 变量：地图编辑器与引擎之间的桥梁 🔗

Spawn变量（Spawn Vars）就是地图文本里那些键值对。引擎如何知道speed该写进结构体的哪个字节位置？答案是偏移量映射表。

在 fields 表 中，每一行都是一条"键名→字段偏移→类型"的映射规则：

{"classname", FOFS(classname), F_LSTRING}, {"origin", FOFS(s.origin), F_VECTOR}, {"health", FOFS(health), F_INT}, {"target", FOFS(target), F_LSTRING},

当解析到health "50"时，G_ParseField 找到对应行，按F_INT类型解析数值，再写入ent指针加偏移处的内存——无需任何字段逐个赋值，全靠这张表"路由"。

具体某个实体初始化时，则通过一组带默认值的便捷函数读取变量，例如：

• G_SpawnFloat( "speed", "200", &ent->speed )—— 地图没写speed就用默认值 200
• G_SpawnInt( "notsingle", "0", &i )—— 判断是否单人模式专用实体
• G_SpawnString( "targetname", "", &ent->targetname )—— 读取目标名

这套机制的意义在于：关卡设计师不需要懂代码，只需在编辑器里改参数，speed、wait、health等变量名在fields[]表中登记后即可生效。

spawns 注册表：classname 如何决定实体行为

结构体填好了，接下来要让实体"活"起来。G_CallSpawn负责按classname分派初始化函数，其查表逻辑见 G_CallSpawn：先查道具表bg_itemlist（弹药、武器等物品），再查普通实体注册表spawns[]。

spawns 注册表 是一张"名字→函数"的目录，节选如下：

{"func_door", SP_func_door}, {"trigger_hurt", SP_trigger_hurt}, {"target_speaker", SP_target_speaker}, {"info_player_start", SP_info_player_start},

以 SP_func_door 为例：它读取speed、wait、dmg、lip等 Spawn 变量，设置被卡住时的伤害回调e_BlockedFunc，计算门的移动距离，最终把门注册进物理碰撞世界。一个看似简单的"门"，正是这条流水线的完整缩影。

如果classname在两张表里都找不到，G_CallSpawn会打印红色错误信息并触发延迟关服——这是 Mod 开发者最常撞见的报错之一。

每帧心跳：Think 循环让实体持续运作 ⚡

生成只是开始。每一帧，服务器都会遍历所有实体调用 G_RunThink：

• 若nextthink > 0且已到期，执行实体的e_ThinkFunc回调
• 随后更新绑定在该实体上的 ICARUS 脚本（Jedi Academy 的 NPC 行为脚本系统）

nextthink字段让每个实体拥有自己的"下次行动时刻"：门的滑动、探照灯的旋转、NPC 的决策，都是这样以事件驱动的方式调度，而非每帧盲目执行。配合结构体中的target/targetname引用链，一个触发器可以激活一扇继电器、继电器再触发一扇门——关卡逻辑像电路一样层层传导。

配套工具视角：用 ModView 观察实体模型

实体结构体里的model字段指向渲染模型。仓库自带一个图形化工具 ModView，可以加载并浏览游戏中的角色与道具模型，适合配合实体系统源码理解model、model2字段对应的实际资源。

小结：一张表看懂核心文件

一句话总结：gentity_t是"数据"，Spawn 变量是"配置"，spawns[]表是"行为路由"，Think 循环是"心跳"。四者协作，让 Jedi Academy 的每张地图从纯文本成长为可交互的星球大战世界。这套 Quake 3 引擎谱系下的实体架构，至今仍是学习游戏服务器架构的经典范本。