SuperAPI AI 工具集

tinyworld-island-and-planes

编程与开发

查看项目

更新于 10-30 12:08

技能介绍

该技能面向 tiny-world-builder 项目中与岛屿和飞机系统相关的开发工作,内容以代码坐标、函数与文件位置的约定为主。

用途 适用于修改家岛(home island)布局、边缘装饰、岛屿底面、赞助横幅(autoincentive sponsor banner),以及飞机/农用喷洒机(plane / crop-duster)系统的场景。文档以“实现说明 + 约束”的方式描述现有系统,帮助开发者在不破坏既有结构的前提下做改动。

主要内容 坐标与相机朝向:家岛以世界原点为中心,草地顶部为 y=0,泥土层向下延伸。DIRT_H=0.55 为可见泥土块高度。默认相机方位角 DEFAULT_AZIMUTH = π0.32、极角 DEFAULT_POLAR = π0.30,相机位于 +X +Z 象限看向原点,+Z 面为岛屿“正面”。

网格与尺寸:GRID(默认 8,最大 20,范围 HOME_GRID_MIN 到 HOME_GRID_MAX)乘以 TILE(=1)决定边缘长度,半宽为 (GRID*TILE)/2。

buildHomeBorder() 构建流程:定义在约第 16340 行,每次家岛网格变化时重建底面与边缘装饰,依次清空 homeBorderGroup 子节点、创建底面板块、级联倒置阶梯底面、添加火箭引擎、添加边缘装饰、准备渲染、构建远景世界与岛下云层。凡应随岛屿重建的元素都应追加在该函数内。

底面细节与粒子:部分圆形底面管道会从外侧端发出清水、浑水或蒸汽,由 23-particles-clouds.js 中的管道发射器系统实现,addIslandUtilityUnderside 注册约 32% 的管道段,粒子上限 140,仅在 camera.position.y < 4 时生成;水/浑水受重力下落,蒸汽上升扩散。

材质与着色器:岛屿外壳材质使用世界 UV 着色器通道,草地方块侧面使用 M.boardSide,应呈现泥土而非岩石;M.boardSideEdge 可显示更深的土层到岩层条带;底面使用 textures/island-underside-voxel.png,替换图需无缝且为 2 的幂。islandShellMaterial() 会保留 ShaderMaterial 的 uniform 与源码,避免侧面克隆变成黑色外壳。Voxel bevel 设置会影响底面与边缘细节,最大 bevel(0.06)会让合并几何体增长约 13 倍,建议保持适度;远景幽灵岛装饰刻意不启用 bevel 以保证性能。

可编辑岛屿 LOD 与整岛选择/删除:由距离门限与数量预算两道闸门决定 LOD,距离门限为 max(40, span*5.2) 内全量,数量预算在 14 座岛以内全部全量,之后为 12/11/10。用选择工具点击岛屿侧面可选中整岛,通过 setIslandSelectionOutline 显示轮廓并抬起移动手柄;选中整岛后按 Delete/Backspace 调用 removeEditableIsland,可撤销。家岛不可移动,因为其可编辑表面位于共享世界网格中,仅 homeBorderGroup 是变换组。岛屿引擎只能从下方选中。

岛屿放置全息投影:激活岛屿工具后,悬停岛屿会在 4 个空闲基本方位同时显示空白岛全息投影,占用侧与家岛原点会被过滤;悬停高亮(uBase 0.10→0.36),点击放置。文档提醒需先检测全息投影悬停并使锚点保持稳定,否则点击时投影会消失;克隆幽灵轮廓时须先收集网格节点再 add(hull),避免栈溢出。新放置的可编辑岛屿会以蓝白色条纹/隧道 + 到达闪光的形式“跃迁”出现,由 startEditableIslandWarpArrival 与 tickEditableIslandWarpArrivals 实现;存档变换仍为 island.positionX/Y/Z + rotationY。

引擎与系泊:家岛火箭引擎保留厚重体素外壳,喷射羽流是少量静态或简单 X 翻转的着色器面片,只在底面可见,避免变成每层火焰立方体;旧体素构建器保留为不活跃的遗留辅助函数。可编辑岛屿的举升引擎为静态体素引擎,螺旋桨朝下,推进/羽流/辉光系统关闭,不注册到 islandRocketFlames 或 islandRocketEngines;引擎槽位 1 和 3 顺时针、2 和 4 逆时针旋转。系泊电缆是点对点世界装饰,只存锚点记录(scope 为 home 或 island,可选 islandId 与局部 {x,y,z}),在不可拾取的 mooringGroup 下重建 TubeGeometry,并纳入撤销/导出/保存状态;家岛网格变化、起始场景重置等情况下需用 clearMooringCables() 清除,导入时可在岛屿重建后用 replaceMooringCables() 恢复。

赞助横幅:PNG/JPG 以 AUTOINCENTIVE_BANNER_DATA_URL(约 41 KB base64 JPEG)内联,避免额外 HTTP。同一数据 URL 用于左上角 Tiny World 字标旁的固定 DOM 横幅(宽屏显示在字标旁,中等宽度落到下方,手机宽度隐藏),以及 Workspace 设置面板中的赞助商 logo;横幅可点击,打开 https://x.com/Autoincidentiv3。旧版 3D 岛屿正面布幔(buildIslandFrontBanner / tickIslandBanners)已从场景移除,函数保留但不再生效。更换美术资源时需同时替换数据 URL 并保持 2.5:1 宽高比,宽度约为 GRID*0.7。

飞机 / 农用喷洒机系统:定义在农用喷洒机路由/状态部分(约第 26200 行),包含 3 架飞机组成的池(planes[]),以编队或单机形式出现。持久化设置 tinyworld:render:planesEnabled 控制整个系统,目前默认关闭;关闭时不加载 GLB/纹理并清除隐藏横幅与喷洒粒子。每个周期随机选择两种运行:startDustingRun() 用 planDustingCurve() 在作物格上方扫过;startBannerRun() 用 planBannerCurve() 在岛屿后方飞行,使拖曳文字横幅在天空背景下清晰可读,路径位于 target.z - (GRID0.5) - (GRID2)(即后缘后方约 2 个岛长),高度为 Math.max(renderCloudHeight + 0.2, FLIGHT_CRUISE_ALT - 1.6)。引擎声使用喷气/火箭音效 foley-rocket-engines-1..4,而非螺旋桨音效。拖曳布幔使用 updatePlaneBannerFlap 沿 X 轴传播正弦波,横幅文字来自 BANNER_MESSAGES。

修改布局时的约束 “正面”为 +Z;南北东西对应 ±X/±Z,不要假设 Y 向上的屏幕坐标。新岛屿工具创建的是可编辑岛屿板而非单元格对象,拥有自己的逻辑板坐标,常规工具仍用 setCell(),岛屿组通过手柄处理 X/Y/Z 与 Y 旋转;不暴露缩放。新可编辑岛屿不应通过 setCell() 为每个默认草地格播种,而应保持默认草地虚拟、为板添加一个可拾取的默认表面网格,仅在用户编辑某格后才生成稀疏的逐格网格。重复岛屿底面复用家岛的细节层:addIslandUtilityUnderside() 用于底面管道/线缆/盒体,addIslandEdgeDressing() 用于草地/泥土/岩石边缘块;新增边缘装饰须加在 addIslandEdgeDressing() 内。任何附着在岛屿上的动画都须由中央动画循环驱动(调用点靠近 renderer.setAnimationLoop(animate) 中的 updateCropDuster(dt))。重复岛屿使用 LOD:选中/近处全量显示,中/远处显示廉价代理板,隐藏岛屿跳过内容、底面细节与引擎螺旋桨跳动,新增逐岛动画或装饰前须保留该机制。

适用场景与限制 适用于熟悉该项目代码库的开发者进行岛屿与飞机相关改动与评审。文档给出的是具体实现约定与易错点,不构成独立产品功能说明;未提供该技能自身的安装方式、收费或平台支持信息。验证部分提到改动后执行 node too 相关检查,但资料在此处截断,完整验证步骤暂未提供。