ShowH5 使用教程

快速入门

ShowH5 是一款积木式可视化编辑器，你无需编写代码，只需拖拽元素、拼接积木，即可创建交互式 H5 页面和小游戏。本节将带你完成第一个作品。

创建第一个作品

一个最小示例

下面是一个最简项目的效果 —— 一个按钮，点击后改变文本内容。点击右侧按钮可直接在编辑器中打开此示例：

元素类型

ShowH5 提供 12 种元素类型，覆盖 H5 页面与小游戏开发所需的所有基础组件。每种元素都有一组可配置的属性，通过右侧属性面板进行编辑。所有元素共享基础属性 x、y、w、h、visible。

元素属性一览

积木分类

积木是 ShowH5 的核心。每块积木代表一个具体操作，拼接在一起即可组成完整逻辑。积木按功能分为 7 大分类。在下方搜索框中输入关键词，或点击分类按钮筛选，点击任意积木卡片可查看详细用法。

事件 Events 外观 Looks 运动 Motion 控制 Control 数据 Data 更多 More 游戏 Game

变量系统

变量用于在脚本中存储和传递数据。ShowH5 的变量系统结合了显式读写与插值语法两种方式，让动态内容变得简单。

${变量名} 插值语法

在任何文本类属性（文本元素、按钮文字、提示信息等）中，你可以使用 ${变量名} 语法引用变量。运行时，ShowH5 会自动将占位符替换为变量的当前值。

// 文本元素的内容属性
"text": "当前得分：${score} 分"

// 当 score = 100 时，显示为：
// 当前得分：100 分

设置与读取变量

使用数据分类下的积木来操作变量。首先在项目设置中声明变量，然后在脚本中读写。

声明变量（在项目 variables 数组中定义）：

"variables": [
  { "name": "score", "value": 0 },
  { "name": "userName", "value": "玩家" },
  { "name": "isPlaying", "value": false }
]

设置变量（使用 data_set_var 积木）：

{ "type": "data_set_var",
  "params": { "name": "score", "value": 100 } }

修改变量（数值增减，使用 data_change_var 积木）：

{ "type": "data_change_var",
  "params": { "name": "score", "delta": 10 } }
// score 从 100 变为 110

读取输入并存入变量（使用 data_set_input 积木）：

{ "type": "data_set_input",
  "params": { "element": "e3", "name": "userName" } }

变量使用场景

• 记分系统：用 ${score} 显示得分，用 data_change_var 加分。
• 表单收集：将输入框内容存入变量，再拼接显示。
• 状态管理：用布尔变量控制游戏开始/暂停状态。
• 计时器：配合 more_timer 积木实现倒计时显示。

脚本系统

ShowH5 采用事件驱动的脚本系统。每个脚本绑定到一个目标元素和一个事件，由一串按顺序执行的积木组成。当事件触发时，脚本中的积木从上到下依次执行。

脚本结构

{
  "id": "s1",              // 脚本唯一 ID
  "target": "e2",         // 目标元素 ID（事件绑定到此元素）
  "event": "event_click",  // 触发事件类型
  "params": {},             // 事件参数（如按键代码）
  "blocks": [               // 积木序列，从上到下执行
    { "type": "action_set_text",
      "params": { "element": "e1", "text": "已点击" } },
    { "type": "action_set_color",
      "params": { "element": "e1", "color": "#34A853" } }
  ]
}

绑定事件到元素

每个脚本通过 target 字段绑定到一个元素，通过 event 字段指定触发条件。一个元素可以绑定多个脚本（对应不同事件），一个事件也可以触发多个积木。

脚本示例：点击切换显示

下面的脚本实现「点击按钮后隐藏自身并显示另一元素」的效果：

{
  "id": "s2",
  "target": "btnToggle",
  "event": "event_click",
  "params": {},
  "blocks": [
    { "type": "action_hide",
      "params": { "element": "btnToggle" } },
    { "type": "action_show",
      "params": { "element": "panelDetail" } },
    { "type": "action_set_text",
      "params": { "element": "lblStatus", "text": "详情已展开" } }
  ]
}

控制流积木的嵌套

控制积木（如 control_if、control_repeat）可以包含子积木，形成嵌套结构：

{ "type": "control_if",
  "params": { "condition": "${score} >= 100" },
  "children": [
    { "type": "action_alert",
      "params": { "message": "恭喜通关！" } },
    { "type": "control_stop", "params": {} }
  ] }

游戏开发

ShowH5 内置游戏分区积木，支持 2D 和 3D 游戏开发。游戏积木封装了精灵管理、碰撞检测、主循环、3D 渲染等底层逻辑，让你专注于玩法设计。

2D 游戏开发流程

2D 游戏示例：弹跳球

一个经典的小球弹跳游戏 —— 小球下落碰到底部反弹，配合分数累加。点击下方按钮可直接在编辑器中体验并修改：

3D 游戏开发流程

3D 游戏基于 Show3D 自研引擎 v4.0 渲染（WebGL GPU 优先，HiDPI 自适应分辨率 + SMAA 抗锯齿 + CSM 级联阴影 + PCSS 软阴影 + EffectComposer 后处理 12+ 特效 + 骨骼动画 + GPU 粒子 + GLTF/OBJ/STL 模型加载 + WebXR VR/AR + KTX2 纹理压缩 + 内置物理引擎，无 WebGL 时自动回退 CPU 软件渲染），使用 game_3d_* 系列积木。典型流程如下：

• 初始化场景：用 game_init_canvas 创建画布，再用 game_3d_add_cube / game_3d_add_sphere / game_3d_add_cylinder / game_3d_add_cone / game_3d_add_torus / game_3d_add_capsule / game_3d_add_plane 添加基础 3D 物体。
• 高级几何体：用 game_3d_add_shape 积木可创建 57 种几何体（含 torusKnot/icosahedron/dodecahedron/lathe/tube/text3D/heart/diamond/crystal/mobiusStrip/kleinBottle/supershape/parametricSurface 等高级形状）。
• 设置相机：用 game_3d_set_camera 调整相机位置与朝向目标（look-at），控制视角。
• 添加光源：用 game_3d_add_light 配置灯光（支持 6 种：point/directional/spot/ambient/hemisphere/rectarea，支持多光源），使物体可见并产生阴影。
• 高级材质：用 game_3d_set_material 设置基础材质；用 game_3d_set_pbr_material 设置 PBR 物理材质（9 种材质类型：standard/physical/phong/toon/basic/lambert/normal/depth/matcap，含金属度/粗糙度/清漆/次表面散射）。
• 阴影与后处理：用 game_3d_set_shadow 开启阴影贴图，game_3d_set_csm 开启 CSM 级联阴影（大场景阴影精度），game_3d_set_postfx 开启 EffectComposer 后处理（Bloom/SSAO/DOF/GodRay/色差/暗角等 12+ 特效叠加）。
• 模型加载：用 game_3d_load_model 加载外部 GLTF/OBJ/STL/PLY 模型文件，支持二进制与 ASCII 格式。
• 粒子系统：用 game_3d_add_particles 创建 GPU 粒子系统（发射器/生命周期/速度/大小/颜色）。
• 骨骼动画：用 game_3d_play_animation 播放骨骼蒙皮动画（Bone/SkinnedMesh/AnimationClip/AnimationMixer）。
• VR/AR：用 game_3d_enter_vr / game_3d_enter_ar 进入 WebXR 沉浸式会话（支持手柄追踪）。
• 纹理压缩：用 game_3d_load_ktx2 加载 KTX2/Basis 超纹理压缩（显存占用降低 75%）。
• 动画循环：在 game_loop 中调用 game_3d_rotate 旋转物体，实现动画。
• 交互控制：用 game_is_key_down 检测 WASD 按键，event_touch_move 处理触屏转向，实现第一人称漫游。

外部引用 Show3D 库（脱离编辑器使用）

如果你想在自己的网站或外部应用中使用 Show3D 引擎（无需打开 ShowH5 编辑器），可以直接通过 <script> 标签引用。引擎由 ShowH5 服务直接托管，不依赖任何第三方 CDN。

<!-- 一行引入，引擎挂载到全局 window.SH5_3D -->
<script src="https://h5.xcmdy.top/3d"></script>
<script>
  var S = SH5_3D;
  console.log('Show3D 版本:', S.version);  // 4.0.0
  var renderer = S.createRenderer(document.getElementById('canvas'));
  renderer.render([...], cam, lights, {});
</script>

支持的引用路径：

• /3d — 主入口（外部应用引用此路径，浏览器直接访问显示文档页）
• /3d/show3d.js / /3d/show3d.min.js — 显式文件名
• /3d?raw=1 — 强制返回 JS（不跳转文档页）
• /3d/docs — SDK 文档页（用法/API/在线 Demo：点击打开）
• /3d/api — API 概览 JSON（程序化查询：点击查看）

3D 示例：旋转立方体

一个旋转的 3D 立方体演示 —— 使用 Show3D v4.0 引擎渲染（HiDPI 高清输出 + SMAA 抗锯齿 + PCSS 软阴影，无 WebGL 时回退 CPU 软件渲染），通过 game3d 系列积木创建场景并持续旋转。点击下方按钮可直接在编辑器中体验：

3D 示例：第一人称冒险游戏

一个完整的 3D 第一人称漫游游戏 —— 使用 game_3d_* 系列积木构建场景，支持 WASD 键盘移动和触屏滑动转向。场景包含地面、墙壁、发光宝石，展示 Show3D 引擎的光照、阴影、材质和反射特效。

3D 游戏控制积木

3D 冒险游戏使用了以下关键积木来实现键盘和触屏控制：

• game_is_key_down —— 检测某个按键是否正在按下，结果存入变量（true/false）。在 game_loop 中每帧调用，实现 WASD 持续移动。按键名使用 KeyboardEvent.code 格式（如 KeyW、KeyA、Space）。
• event_touch_start / event_touch_move / event_touch_end —— 触屏事件积木，分别在手指触摸开始、滑动、离开时触发。触摸坐标自动存入 state.touchX / state.touchY，通过 game_get_touch_x / game_get_touch_y 读取。
• game_get_touch_x / game_get_touch_y —— 获取当前触摸点的屏幕坐标，存入指定变量。用于实现虚拟摇杆、滑动转向等移动端控制。
• game_3d_set_camera（增强版） —— 设置相机位置 X/Y/Z 和看向目标 tx/ty/tz（look-at）。通过每帧更新相机位置和朝向，实现第一人称视角漫游。
• game_3d_get_pos —— 获取 3D 物体的当前位置坐标，存入三个变量。用于碰撞检测、距离判断等游戏逻辑。
• game_3d_set_material —— 设置物体材质，支持预设类型（metal/gold/plastic/glass/wood/rubber）和自定义参数（shininess/metalness/roughness），驱动 Blinn-Phong 光照和环境反射。
• action_math_sin / action_math_cos —— 三角函数计算，用于根据视角朝向角（yaw）计算移动方向向量。

特效引擎

为了让游戏画面更有冲击力，ShowH5 内置了一整套特效积木，覆盖屏幕震动、爆炸、天气、光效等常见表现。所有特效均可在 game_loop 或事件脚本中触发，叠加使用即可组合出丰富的视觉效果。

• 屏幕震动：game_screen_shake —— 让画面产生短暂抖动，常用于爆炸、受击、重击等瞬间，增强打击感。可设置强度与持续时间。
• 爆炸效果：game_explosion —— 在指定位置生成爆炸粒子与火光，适合摧毁、击杀等场景。
• 冲击波：game_shockwave —— 生成一圈向外扩散的环形波纹，用于表现能量释放、爆炸余波。
• 拖尾效果：game_trail —— 为移动中的精灵添加渐隐拖尾，常用于子弹、飞行物、高速移动角色。
• 下雨：game_rain —— 全屏降雨天气特效，可控制雨量与速度，营造阴雨氛围。
• 下雪：game_snow —— 全屏降雪天气特效，雪花缓慢飘落，适合冬日场景。
• 烟雾：game_smoke —— 生成上升消散的烟雾粒子，用于爆炸余烟、火焰、机械排气等。
• 闪电：game_lightning —— 瞬间全屏闪白并伴随电光，用于雷暴、技能释放等特效。
• 发光：game_glow —— 为精灵或区域添加发光光晕，用于道具拾取、能量体、特效高亮。
• 清除特效：game_clear_effects —— 一次性清除当前所有特效粒子，用于场景切换、重置或回收资源。

导出与发布

完成作品后，ShowH5 提供三种方式让你的作品走向用户：导出 HTML、发布到社区、部署静态站点。

导出 HTML

点击编辑器右上角「导出」按钮，可将作品打包为单个独立 HTML 文件。该文件包含全部元素、脚本和运行时引擎，无需服务器即可在浏览器中直接打开运行。

• 文件自包含，无外部依赖（图片/音频等通过 URL 引用）。
• 适合本地演示、邮件附件、离线分享。
• 导出的 HTML 可直接嵌入到其他网站的 iframe 中。

发布到社区

点击「发布」可将作品提交到 ShowH5 社区。发布后：

• 获得专属分享链接，他人点击即可在线体验。
• 作品出现在社区广场，可被其他用户浏览、点赞、收藏。
• 支持设置封面图、简介和标签，提升曝光度。
• 可随时更新已发布作品，链接保持不变。

部署静态站点

导出的 HTML 文件可以部署到任何静态托管平台：

部署示例（Nginx）

# nginx.conf
server {
    listen 80;
    server_name your-domain.com;
    root /var/www/showh5;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

协作系统

ShowH5 提供实时联机协作功能，让你可以邀请伙伴一起编辑同一个作品。无论是分工制作素材、共同调试脚本，还是多人头脑风暴创意，协作系统都能让大家在同一舞台上实时看到彼此的操作。单个房间最多支持 16 人同时在线协作。

会员等级与协作席位

协作席位数由你的会员等级决定。发起者创建协作房间时，可加入的人数上限按当前等级的席位数计算。

如何发起协作

如何加入协作

收到发起者分享的协作链接后，点击链接即可进入对应的协作房间。也可以在编辑器的协作面板中直接粘贴房间 Token 或链接加入。加入后你的操作会实时同步给房间内的所有人，同时你也能看到他人的编辑动作。

发起者权限

作为协作房间的发起者，你拥有完整的管理权限，可对房间和成员进行管控：

• 踢出成员：可将违规或无关成员请出房间，被踢出者无法再次通过原链接加入。
• 禁言成员：可对个别成员开启禁言，限制其在聊天室发言，但不影响其编辑操作。
• 违禁词管理：可设置违禁词列表，聊天室中命中违禁词的内容会被自动屏蔽，维护协作环境健康。

聊天室功能

每个协作房间都内置聊天室，成员可以在编辑的同时实时交流。聊天室支持文字消息，方便讨论玩法、分配任务、反馈问题，无需切换到第三方通讯工具。

保存与导出归属

常见问题