Freecam
[!INFO] Git Commit:
f56a98b| Updated: 2026-08-01
Freecam（modid freecam-gtnh）是一个 1.7.10 / GTNH 的纯客户端自由相机 mod。
它把 Minecraft.renderViewEntity 从玩家换成一个伪造的 EntityPlayer 子类，
从而在不移动、不冻结、不修改服务器世界的前提下，让玩家以独立视角四处观察。
该项目由 GTNewHorizons 维护，作者 Caedis，上游说明为 “Modern Freecam for 1.7.10”，
TripodSlot 的注释标注改编自 hashalite/Freecam。
本 mod 不注册任何方块、物品、实体、附魔、维度、群系、成就或指令。 它只有 3 个按键和 3 个配置文件（共 10 个配置项），全部能力来自 7 个 Mixin。 详见下方本 mod 不具备的内容。
主要特性：
- 自由相机：按 F4 进入 / 退出，松开 F4 的瞬间才真正切换（边沿触发）；
- 三脚架机位：按住 F4 时按数字键 1~9 可放置并复用 9 个长期驻留的机位；
- 玩家操控模式：可把操作权交还玩家，准星与点击判定回到玩家身上；
- 渲染距离收边：相机被限制在渲染距离边缘内侧 2 个区块以内，且修正走碰撞感知路径；
- 碰撞模式可配：撞所有方块 / 穿非不透明方块 / 穿门窗栅栏门 / 完全无碰撞；
- 移动模式可配：STATIC（立即停）或 CREATIVE（带惯性，默认）；
- 叠加层隐藏：自由相机中默认隐藏 Waila 提示栏、Thaumcraft 护目镜与检测器标记、HoloInventory 全息投影；
- 可选全亮度与去浸没雾：均以"渲染时改读值"实现，不会污染持久化游戏设置；
- 服务器可控：
disabled与collisionMode是服务端同步项，另有三个@Config.Sync渲染项。
核心机制
- 自由相机状态机 -
FreecamController的启用/退出/每 tick 流程、两种移动积分、渲染距离收边、视角偏移常量 - 脱离实体 -
CameraEntity extends EntityPlayer的子步进碰撞、分轴解算与 18 项被裁掉的行为 - 三脚架相机槽位 -
TripodSlot9 个槽位与TripodRegistry，以及enable()与enableTripod()的实质差异 - Mixin 加载阶段 -
TargetedMod目标判定、早期 vs 后期两阶段、全部 7 个 Mixin 与 3 个 mixin 配置 - 兼容模组 -
Mods四个取值的探测与分支：Angelica、Controlling、Et Futurum
热键列表
3 个按键全部由 ClientEventHandler 构造时经 ClientRegistry.registerKeyBinding 注册，
类别 key.categories.freecam（显示为 Freecam）。
| 按键 | 默认键 | 说明 |
|---|---|---|
| 切换自由相机 | F4 |
按下进入按住态、松开才切换；按住期间是另外两个键的修饰键 |
| 重置相机 | KEY_NONE（未绑定） |
清空全部三脚架机位，需按住 F4 后松开触发 |
| 玩家控制开关 | KEY_NONE（未绑定） |
把操作权交还玩家，需按住 F4 后松开触发 |
⚠️ 只有 F4 有默认按键，另外两个默认未绑定，必须在选项界面手动指定。
⚠️ 全部 UI 文案只提供 en_US.lang，没有 zh_CN.lang。
配置项
3 个配置类在 FreecamMod.preInit 中经 GTNHLib ConfigurationManager 注册，modid freecam-gtnh。
带 ✅ 的为 @Config.Sync 服务端同步项。
GeneralConfig
| 配置项 | 类型 | 默认值 | 同步 | 说明 |
|---|---|---|---|---|
| 已被禁用 | boolean |
false |
✅ | 总开关；被检查 4 处，激活期间变开会立即强制退出 |
| 相机碰撞模式 | CollisionMode |
FULL |
✅ | FULL / IGNORE_TRANSPARENT / IGNORE_OPENABLE / NONE |
| 受伤时禁用 | boolean |
true |
❌ | 非创造模式玩家血量下降时排程退出 |
MovementConfig
| 配置项 | 类型 | 默认值 | 同步 | 说明 |
|---|---|---|---|---|
| 移动速度 | float |
1.0f |
❌ | 范围 @RangeFloat(0.2, 10.0)；全 mod 唯一带范围约束的项 |
| 移动模式 | MovementMode |
CREATIVE |
❌ | CREATIVE（惯性，速度 ×2.0）/ STATIC（立即停，×0.5） |
MiscConfig
| 配置项 | 类型 | 默认值 | 同步 | 说明 |
|---|---|---|---|---|
| 全亮度 | boolean |
false |
✅ | 渲染时把 gammaSetting 读值换成 100.0F，不改持久化设置 |
| 禁用浸没雾 | boolean |
false |
✅ | 把视点方块换成 Blocks.air，只对 Material.water / Material.lava 生效 |
| 覆盖层可见性 | OverlayVisibility |
HIDE |
✅ | HIDE / SHOW，是 3 个后期 Mixin 的统一门控 |
| 进入视角 | Perspective |
INSIDE |
❌ | INSIDE / FIRST_PERSON(+0.4) / THIRD_PERSON(−4.0) / THIRD_PERSON_MIRROR(+4.0, yaw+180) |
| 显示手部 | boolean |
false |
❌ | 唯一同时驱动原版 Mixin 与 Angelica 事件监听器的项 |
运行时数值（非常量配置）
以下数值不是配置项，是 FreecamController 的常量或实例字段，不持久化：
| 数值 | 值 | 说明 |
|---|---|---|
| 速度倍率 | 默认 1.0F，范围 0.1~10.0 |
滚轮调整，步进 0.1F；reset() 后回到 1.0 |
| 疾跑倍率 | 1.5 |
常量 SPRINT_MULTIPLIER |
| 对角线归一化 | sin(45°) |
前进 + 平移同时进行 |
| 子步最大位移 | 0.2D（上限 64 步） |
常量 MAX_STEP / MAX_STEPS |
| 收边余量 | 2 个区块 | 常量 CLAMP_MARGIN_CHUNKS |
| 插值/摩擦 | 0.15 / 0.6 |
CREATIVE_ACCELERATION / CREATIVE_FRICTION |
本 mod 不具备的内容
本节逐条列出源码中确实不存在的内容，附 grep 证据。执行目录为
/Users/evlos/a/mirror/Freecam/src/main/java，全部命令无匹配。
| 维度 | grep 证据 | 结论 |
|---|---|---|
| 方块 | grep -rn "registerBlock|registerItem|registerTileEntity" → 无匹配；grep -rn "extends Block" → 无匹配 |
0 个方块，连方块子类都没有 |
| 物品 | grep -rn "new Item(" → 无匹配 |
0 个物品。ItemStack 仅在 CameraEntity 中作为"返回空"的 4 个覆写出现 |
| TileEntity | grep -rn "TileEntity" → 无匹配 |
0 个 TileEntity |
| 实体注册 | grep -rn "registerEntity" → 无匹配 |
0 个注册实体。CameraEntity 继承 EntityPlayer 但从不加入世界实体列表，仅作 renderViewEntity |
| 附魔 | grep -rn "Enchantment" → 无匹配 |
0 个附魔 |
| Buff/Debuff | grep -rn "Potion" → 无匹配 |
0 个药水效果 |
| 群系 | grep -rn "Biome" → 无匹配 |
0 个群系 |
| 成就 | grep -rn "Achievement" → 无匹配 |
0 个成就 |
| 维度 | grep -rn "WorldProvider|DimensionManager|registerDimension" → 无匹配 |
0 个维度 |
| 多方块 | grep -rn "Multiblock|MapGenStructure|WorldGenerator" → 无匹配 |
0 个多方块结构、0 个世界生成 |
| 指令 | grep -rn "ICommand|ClientCommandHandler|addChatCommand|CommandBase" → 无匹配 |
0 条指令。CameraEntity.canCommandSenderUseCommand 反而被覆写为 false |
| 物品效果 | 同"物品"行 | 0 个物品效果 |
其它需要澄清的"不存在"：
- 没有
EarlyMixinsLoader.java。早期 Mixin 由core/FreecamCore.java自身 （IFMLLoadingPlugin+IEarlyMixinLoader）加载；mixins/下只有LateMixinsLoader.java一个加载器类。 mixins.freecam-gtnh.json不被任何代码引用。grep "mixins.freecam-gtnh.json" src/main/java无结果，实际生效的只有.early.json与.late.json两个配置。- 没有
GeneralConfig之外的单例配置类。共 3 个配置类 10 个字段，已在配置项章节全部列出。 Mods枚举里没有 Thaumcraft / Waila / holoinventory。这三个 mod 只出现在TargetedMod（加载期 Mixin 判定）中，与运行时判定是两套独立机制。- 语言文件只有
en_US.lang，没有zh_CN.lang或其它语言。 - 没有纹理、模型、音效资源。
assets/下仅freecam/lang/en_US.lang一个文件。 - 不对服务器世界做任何修改。全部 23 个 Java 文件中没有一次方块/实体/世界数据的写入。
- 无访问转换器以外的原生补丁。
META-INF/freecam_at.cfg只有 1 行（公开SoundManager$SoundSystemStarterThread）；FreecamCore.getASMTransformerClass()返回null，getModContainerClass()/getSetupClass()/getAccessTransformerClass()全部返回null。 @Mod声明为acceptedMinecraftVersions = "[1.7.10]"、acceptableRemoteVersions = "*"， 且networkCheck逻辑为：检查服务端时要求remoteVersions含freecam-gtnh， 检查客户端时恒返回true。
源码索引
23 个 Java 文件（com.caedis.freecam，共 1599 行）：
| 路径 | 行数 | 职责 |
|---|---|---|
FreecamMod.java |
68 | @Mod 主类，注册 3 个配置类，networkCheck |
ClientEventHandler.java |
180 | 注册 3 个按键，6 个 @SubscribeEvent 处理器 |
core/FreecamCore.java |
50 | coremod 入口，挂载早期 Mixin |
camera/FreecamController.java |
403 | 状态机（真正的核心逻辑） |
camera/CameraEntity.java |
254 | 脱离实体与子步进碰撞 |
camera/RevealGate.java |
15 | 叠加层隐藏的统一门控 |
camera/tripod/TripodRegistry.java |
28 | 9 个机位的 EnumMap |
camera/tripod/TripodSlot.java |
47 | 槽位枚举与按键映射 |
config/GeneralConfig.java |
29 | 3 项 |
config/MovementConfig.java |
22 | 2 项 |
config/MiscConfig.java |
43 | 5 项 |
compat/Mods.java |
49 | 4 个运行时探测项 |
compat/AngelicaCompat.java |
19 | Angelica 手部事件监听器 |
mixins/Mixins.java |
33 | 4 个 Mixin 清单项 |
mixins/TargetedMod.java |
26 | 3 个目标 mod |
mixins/LateMixinsLoader.java |
25 | 后期 Mixin 加载器 |
mixins/early/minecraft/MixinMinecraft.java |
68 | 视角切换屏蔽 + 4 个点击取消 |
mixins/early/minecraft/MixinEntityRenderer.java |
90 | 5 处渲染补丁 |
mixins/early/minecraft/MixinEntityLivingBase.java |
31 | 受伤检测 |
mixins/early/minecraft/MixinMovementInputFromOptions.java |
25 | 清零移动输入 |
mixins/late/waila/MixinOverlayRenderer.java |
19 | 隐藏 Waila 提示栏 |
mixins/late/thaumcraft/MixinRenderEventHandler.java |
49 | 隐藏 4 类 Thaumcraft 标记 |
mixins/late/holoinventory/MixinRenderer.java |
26 | 隐藏全息投影 |
⚠️ 类名与文件名不一一对应：三个后期 Mixin 分别叫 MixinOverlayRenderer、
MixinRenderEventHandler、MixinRenderer，但都放在各自 mod 的子包下
（late/waila/、late/thaumcraft/、late/holoinventory/），唯一区分依据是目录。
⚠️ core/FreecamCore.java 不是相机状态机——状态机在 camera/FreecamController.java。
FreecamCore 只实现 IFMLLoadingPlugin 的 5 个空实现加一个 getMixinConfig()。