Skip to content

DEVLOG.md

Latest commit

 

History

History
202 lines (163 loc) · 15.6 KB

DEVLOG.md

File metadata and controls

202 lines (163 loc) · 15.6 KB
Raw

开发记录

（早期 README 与各版本更新说明，按时间顺序保留）

体素箱庭解谜冒险。当前版本包含区域 1「翠绿温室」的完整关卡（方块体素版），以及一个机制测试房间。 下一阶段会把体素底层迁移到 Voxel Tools 的平滑地形（雾锁王国式的破坏）。

运行

  1. 用 Godot 4.6（官方版或 Voxel Tools 定制版都可以）打开本文件夹里的 project.godot。
  2. 按 F5 运行。

操作（PS5 手柄优先，Xbox / 键鼠同样支持，界面会自动切换按键图标）

功能 PS5 Xbox 键鼠
移动 左摇杆 左摇杆 WASD
镜头 右摇杆 右摇杆 鼠标
跳跃（仅测试房间） ✕ A 空格
形态能力 □ X 左键 / F
抓取 / 投掷 ○ B E / 右键
加速 R2 RT Shift
切换形态 L1 / R1 LB / RB 滚轮 / Z C
直选形态 十字键 十字键 1–5
俯视模式 △ Y V
回到检查点 Create View R
暂停 Options Menu Esc

形态

形态 重量 能力
滚球 1.0 冲刺（可撞碎玻璃）
钻头 2.5 按住向前钻；静止时向下钻
立方 3.0 空中重压；够重能压动压力板
磁铁 1.4 按住吸附金属墙，推向墙面往上爬
气泡 0.3 喷气上浮；能被上升气流吹起

代码结构

scripts/
  voxel/blocks.gd        方块类型表（颜色、谁能破坏、掉落）——调数值改这里
  voxel/voxel_world.gd   体素世界：分块网格、碰撞、破坏、砂块下落
  voxel/pickup.gd        金币/能源：自动飞入球体
  player/morph_ball.gd   主角：五种形态的物理参数与能力
  player/camera_rig.gd   第三人称镜头
  puzzles/               插槽、能量回路、压力板、气流、检查点、变形站、NOVA 对话触发
  levels/test_room.gd    测试关卡（代码搭建）
  ui/hud.gd              界面
  debug/autotest.gd      自动测试

关卡与测试

  • 默认进入区域 1「翠绿温室」；加参数 -- --level=test 进入机制测试房间。
  • 设计原则：主角默认不能跳（致敬平衡球），高低差靠坡道、弹跳垫和形态能力；往下钻只对松土有效，避免把自己困住。
godot --headless --path . -- --autotest              # 机制测试房间，22 项
godot --headless --path . -- --autotest=greenhouse   # 区域 1 整关测试，按设计路线走到终点

音频

audio/ 下的音乐和音效由 tools/synth_audio.py 程序合成（numpy + ffmpeg）。 区域音乐分三层（底层 / 旋律 / 明亮）同步循环，由 scripts/game/music.gd 按游戏状态自动混音。

画风与素材（v0.6）

  • 方向：可爱外表 + 科幻内核。Kenney 新版粉彩配色——薄荷绿草地、珊瑚色泥土、淡紫科技件、阳光黄点缀。
  • 现成素材放在 assets/，统一从 scripts/art/kit.gd（Kit.model() / Kit.mesh()）取用；授权见 assets/CREDITS.md（Kenney CC0 + OFL 字体）。
  • 树、花、蘑菇、石头是 Prop（scripts/props/prop.gd）：高速滚撞 / 冲撞 / 钻 / 下砸会“啵”地弹飞并掉金币。
  • 界面字体：Fredoka（英文数字）+ 站酷快乐体（中文）；按键提示使用 Kenney Input Prompts 真实按键图标，并直接嵌在 NOVA 的台词里。
  • 素材预览：godot --path . --rendering-driver opengl3 -s res://tools/gallery.gd -- res://assets/kenney/platformer /tmp/out.png

v0.8：大气远景 + 战斗扩充

世界

  • 天空：shaders/sky.gdshader——分层渐变、太阳光晕、地平线积云带、高空卷云、带光环的巨型行星和卫星。每章一套配色（scripts/game/atmosphere.gd）：第一章晴朗上午，第二章工坊黄昏。
  • 远景（scripts/world/）：和玩法世界同一套方块与着色器的“大体素”远景，在后台线程生成（结果会缓存）。
    • 第一章：北面带山峰和瀑布的「云脊」母岛、西边樱花岛、南边小岛群、从云海拔起的石柱、东北方远处的方舟星核塔和其余四座重构塔。
    • 第二章：冒烟的工厂浮岛、慢慢转动的巨型齿轮、锈红色钢桁架、西边远处第一章的浮岛（第一座塔的光柱）。
    • 玩法浮岛底下自动生成向下收拢的巨大岩体（石笋、水晶、垂下的草根），岛边有瀑布流进云海。
  • 第一章新区域：西北角的粉色古树（螺旋树枝平台 → 树屋宝箱 + 记忆碎片 + 眺望星核塔）、南边的锈蚀营地（清光敌人打开笼子救出第 4 只噗噗）、E 高台上的环形天线遗迹和断掉的单轨、18 米高的重构塔（点亮后光柱冲天）、岛边的岩石。
  • 第二章新区域：大烟囱（气泡顺着热气流飘到顶上：宝箱 + 第 4 只噗噗）、储料场的炮台、厂房墙上咬合转动的大齿轮、Boss 场地和更高的重构塔。

战斗

新攻击 操作 说明
踩踏 跳起来落到敌人头上 所有形态都行，踩完弹起来（按住跳弹得更高）
蓄力冲刺 滚球静止时按住能力键，松开 蓄满后冲刺速度 15 m/s，能正面撞碎锈块兽的盾牌
泡泡弹 气泡形态按住能力键，松开 把敌人困在泡泡里飘起来，破掉后摔翻；能包住锈弹
打回炮弹 气泡形态气浪 把飞来的锈弹原路打回去
投掷 抓起物件扔向敌人 砸翻 / 砸晕
新敌人 行为 解法
锈蜂 盘旋，锁定后俯冲（地上有红圈） 俯冲扎地后撞它；跳起来撞/踩；气浪、泡泡弹打落
刺壳虫 背上尖刺，定时收起 收刺时冲撞；钻头无视尖刺；下砸/气浪掀翻
锈炮台 抛物线锈弹 躲开冲过去撞；气浪把炮弹打回去
熔炉守卫（第二章 Boss） 冲锋、震地冲击波、召唤锈蜂、连发锈弹 引它撞石柱晕眩，撞背后的熔炉核心三下；打回的锈弹能直接炸晕它

Boss 战有专门的配乐（tools/synth_boss.py 生成，三层随阶段加强）。

测试

godot --headless --path . -- --autotest              # 机制 + 新战斗（踩踏、蓄力、锈蜂、刺壳虫、炮台、泡泡弹、投掷）
godot --headless --path . -- --autotest=greenhouse   # 第一章整关
godot --headless --path . -- --autotest=gearworks    # 第二章整关（含 Boss）

截图：--shots=<目录> --gh2（第一章新区域）、--gw2（第二章）、--vista（远景）、--level=test --enemies（敌人一览）。

v0.9–v1.0：破坏与重构、完整六章、改装、关卡编辑器

  • 破坏感：草、土、苔、木、树冲刺就碎；锈铁、铺路石要蓄力冲刺；岩石、崖壁、合金是地基。下砸砸出大坑，断开的部分整块塌落。
  • 重构：拆下的每一格都变成「重构物质」。重构点（发光蓝图）可以把瞭望台、断桥、断坡一块块建回来。点亮重构塔时会有重构波，把砸烂的地形飞回原位。
  • 章节：一 温室群岛、二 齿轮工坊、三 晶簇深渊、四 云顶之城、五 锈海（潮汐、锈海吞噬者、灯塔重建）、终章 星核（锈蚀之心、结局与制作人员表）。
  • 改装 PIX（暂停菜单）：用金币买永久升级，跨章节保留。
  • 手柄：✕/A 确认、○/B 返回；设置界面整行高亮，左右调数值；手柄震动可调强度。
  • 关卡编辑器（标题画面）：摆方块和物件（出生点、终点、检查点、金币、宝箱、种子、弹跳垫、上升气流、6 种敌人），一键试玩；5 个本地存档位；导出成 .cube7 文件分享（见 v1.1）。
  • 测试：--autotest、--autotest=greenhouse|gearworks|abyss|city|rust|core；编辑器用 --editor --debugscript=res://scripts/debug/test_editor.gd；手柄菜单用 --debugscript=res://scripts/debug/test_ui_pad.gd。

v1.1：修复与关卡导出导入

  • 标题画面：鼠标左键可以开始、可以点菜单项；打开主菜单时标题缩小上移，菜单不再被遮挡。
  • 掉帧：修复“顿帧”结束判断的 bug（卡一帧时计时器提前触发，time_scale 永远停在 0.25，看起来像帧数骤降）； 破坏开销约降到 1/3（区块脏标记只在边界扩散、道具改为按格订阅、掉落物上限 60、区块重建按渲染组计入预算）。
  • 关卡分享改为导出 / 导入文件（去掉了分享码和上传）：编辑器菜单「导出」写到「文档/立方7关卡/关卡名.cube7」； 「导入……」列出这个文件夹里的关卡，也可以把 .cube7 文件直接拖进游戏窗口。 按内容指纹（方块 + 物件，不含名字）防重复：同一关不会重复导出，本地保存位之间也不会存两份。
  • 新测试：-- --titletest[=截图目录]（标题画面，需窗口/xvfb）、 --chapter=N --debugscript=res://scripts/debug/prof_break.gd（破坏/打怪性能剖析）。

v2.0：奥德赛风的平滑地形、回声探索、马造式编辑器

画面

  • 平滑地形：草、土、岩、沙、崖壁、树冠这些自然材质改由 Voxel Tools 的 Transvoxel 生成平滑曲面（4 层材质混合）， 底层仍然是 0.25 米的体素：破坏、坍塌、重构、编辑器都不变。用标准版 Godot 打开时自动退回 GDScript 的 Surface Nets（scripts/voxel/smooth_mesher.gd），画面一致。
    • 平滑地形按渲染组（16³ 体素）整块生成：TerrainMesher（scripts/voxel/terrain_mesher.gd），每组约 2 毫秒。
    • SDF = 0.5 − (0.55 × 原始填充 + 0.45 × 3×3×3 模糊)：既圆润，又不会吃掉一格厚的细节；模糊用 VoxelBuffer 的 C++ 运算完成。
    • 材质槽位：TerrainPalette（16 种），着色器 shaders/voxel_terrain.gdshader 按槽位混合颜色和“草 / 树冠 / 砂 / 打不坏”的风格。
    • 人造物（箱子、金属、木板、建筑）保留圆角方块，和平滑地形形成“软地形 + 硬积木”的对比；挨着地形的方块面会画出来，不留缝。
    • 远景浮岛、掉落的碎块也用同一套平滑网格。
  • 卡通光照（shaders/toon_light.gdshaderinc）：柔和的明暗交界、冷色的背光面、迎光轮廓上的暖色边缘光（地面不加）、小而柔的高光。
  • 配色调暖调亮（草更黄绿、泥土更橙），去掉自然地形上的格子和铆钉；可破坏方块的边框更含蓄。
  • 柔和环境光遮蔽（设置里可关）。

破坏与重建

  • 坑口由连续噪声决定（不再是逐格随机的麻点）；岩石重击按 Voronoi 裂成几大块崩飞（VoxelChunk.fragment）；泥土碗状坑 + 土块；木头碎成长木片；玻璃薄片；树叶飘落。
  • 碎屑按材质换形状（不规则小石块、土块、木片、薄片）。
  • 断开掉落的大块用平滑网格，小碎块用凸包碰撞，会像石头一样滚。
  • 下落的碎块会砸伤敌人（环境击杀）。
  • 重构动画改为圆角方块；落地后在原位停留 0.3 秒盖住网格重建的几帧，不会闪出空洞；积压多时网格重建预算自动加大。
  • 破坏遍历只扫球内体素、直接读数组，大坑开销降了约 15%。

探索（详见 docs/DESIGN_EXPLORE.md）

  • 回声扫描（L2 / LT / Q / 鼠标中键）：声呐波扫过地形，隔着地层标出回声晶核、种子方块、记忆碎片、宝箱、金矿、晶簇和承重点。
  • 回声晶核：每章最多 5 颗埋在地层深处的晶洞里，拾取时读出一段“星球的回声”（剧情新增的一层）。
  • 形态进化（暂停菜单）：深层回声、回声视界、螺旋钻头（能钻崖壁）、震荡冲撞（能撞开岩石）、共鸣气泡。
  • 每章自动生成的支线：通往晶洞的地下洞穴（荧光菇指路、尽头用松土堵着）、敌人旁边的落石陷阱。全部避开原有谜题，六章整关测试照常通过。
  • 节奏放慢：滚球巡航速度 7 → 6.3 m/s（加速冲刺不变），镜头跟随更从容，限时挑战多 40% 时间。

关卡编辑器（参考《马力欧创作家》）

  • 顶部 10 格快捷栏（L1/R1、数字键 1～0、滚轮），当前物块显示大图标 + 属性说明（撞碎需要几 m/s、钻头可钻、会塌、可燃、导电……）。
  • 全部物块面板（□ / Tab）：按“自然地形 / 建筑 / 可破坏与机关 / 物件 / 敌人”分组，每个都有图标（平滑地形画成土丘、玻璃半透明、发光有光晕、角标表示能不能撞碎 / 钻 / 会不会塌）。
  • 框选铺满 / 清空（L3 或 Shift + 拖），吸管（R3 / Q），撤销 / 重做（Create/View、Ctrl+Z / Ctrl+Y，按住 R2 重做，最多 60 步），从光标处试玩（R2 + △ / Shift+T）。

测试

  • --chapter=1 --debugscript=res://scripts/debug/test_explore.gd（探索系统）、--editor --debugscript=res://scripts/debug/test_editor.gd（编辑器，含新功能）。
  • 测试需要 Voxel Tools 版 Godot 才会走 Transvoxel；标准版走 Surface Nets。

v2.1：主线 = 探索 → 关键道具 → Boss；美术统一、破坏不卡

主线结构

  • 每章都有一枚关键道具「进化芯片」（scripts/explore/chapter_key.gd）：埋在晶洞里（会有一条地下洞穴通过去）， 或压在第一座重构点附近的塌方堆里。回声扫描把它标成金色的「关键道具」。
  • 拿到芯片：PIX 立刻进化出本章的新能力——回声芯片（深层回声）、震荡芯片（震荡冲撞）、螺旋芯片（螺旋钻头）、 共鸣芯片（共鸣气泡）、视界芯片（回声视界）、星核钥匙（终章）。
  • 每章 Boss 身上裹着一层锈封印：没有芯片打不进去，NOVA 会把目标改成“去找芯片”；带着芯片走近，封印共鸣碎掉，开打。
  • 第一章新增 Boss 锈根兽（scripts/enemies/root_hulk.gd）：背着岩甲，撞、钻、砸都没用。 扫描找到场地边木架托着的落石 → 引它冲到木架下 → 撞断木架让落石砸中它 → 岩甲裂开、四脚朝天 4 秒 → 这时打它。三击打倒； 落石用完会一格格重构回来。打倒后终点浮岛的光门才出现。

美术

  • 去掉“塑料感”：地形、积木、模型统一换成哑光材质（粗糙度 0.85～0.92、高光 0.2），整体亮度和饱和度往下收，ACES 对比略加。
  • 每种材质有自己的表面细节法线：草是细密的草叶、岩石是粗颗粒和裂面、泥土是土粒、砂是风纹、树冠是一簇簇叶团； 细节的凹处同时压暗颜色，质感更“实”。草地加了细碎的深浅草点，绿色更沉。
  • 外部模型（Kenney 等）首次实例化时统一换成同一套哑光卡通材质（Kit._matte），和体素世界不再像两套美术。

性能：破坏不再卡顿

  • 地形网格快速路径：直接把 8 位整数 SDF 写进 VoxelBuffer（TerrainMesher.build_vt_fast），每组 0.9 毫秒（原 2.3），几何完全一致。
  • 断开检测（会不会塌）改成延迟 + 分帧：访问戳代替字典、遇到锚点提前退出、每帧 5 毫秒预算。
  • 连续撞击的破坏合批处理，信号在批末一次发出。实测连撞岩壁 p95 9 毫秒；24 个大坑的压力测试平均 57 → 39 毫秒。

手感

  • 钻头原地按住往下钻在哪里都有效：钻出一个漏斗形的坑（坑壁有坡度，能自己滚上来），不会再在原地空转。
  • 向前钻不会把自己钻进地下（高度下限）。

测试

  • test_explore.gd 增加芯片 / 封印检查；第一章整关测试增加“原地下钻 + 爬出来”和锈根兽战斗。
  • 第五章出生点加了一块平台，球不会再顺着平滑沙丘滚进锈海。