【征文计划】我的第一款 AR 应用：用 Rokid JSAR 创建掌上三角洲干员“威龙”-优快云博客

摘要： 曾几何时，AR（增强现实）开发对我来说，是遥不可及的“屠龙之技”，似乎总与复杂的图形学和原生应用开发深度绑定。直到我遇见了 Rokid JSAR，这个专为Web开发者打造的AR开发方案，彻底颠覆了我的认知。它巧妙地将前端技术栈与3D空间计算相结合，让我这样一位仅有前端基础的开发者，也能在短短数小时内，从零开始构建出一款属于自己的AR应用。这篇手记，旨在完整记录我使用 JSAR 打造“掌上太阳系”的全过程，分享这份从二维网页迈向三维空间的激动与思考。

相关链接：

Rokid 开发者论坛 - 探索更多可能与交流心得
JSAR 官方开发手册 - 最权威的技术参考

拨开云雾：初识轻量级 AR 开发方案 JSAR

在深入实践之前，我们有必要先理解 JSAR 的核心理念。简单来说，JSAR 是一个基于 Web 技术的 AR 开发框架。它最大的魅力在于，允许我们使用熟悉的 JavaScript/TypeScript、HTML/CSS（的思想）以及前端生态工具（如 npm、Vite/Webpack 等）来构建可以运行在 Rokid AR 眼镜上的沉浸式应用。

它好比一座桥梁，一端连接着我们熟知的 Web 开发世界，另一端则通往充满无限可能的 3D 空间。JSAR 负责处理所有复杂的底层硬件交互和空间算法，而我们，则可以专注于创意的实现。

软硬兼施：Rokid 生态的协同之力

JSAR 并非空中楼阁，它的强大离不开 Rokid 硬件生态的坚实支撑。从 Rokid Max 到 Station，这些 AR 设备提供的 SLAM（即时定位与地图构建）、手势识别等核心能力，都被 JSAR 巧妙地封装成了简洁的 API 接口。

这种软硬件的深度融合，意味着我们无需关心“陀螺仪数据如何读取”、“空间锚点如何设置”这类底层问题。我们只需要调用一个 API，就能将一个虚拟模型“固定”在现实世界的桌面上。这种“技术下沉，创意上浮”的模式，是 JSAR 能够实现“低门槛”开发的关键所在。

搭建工作台：我的 AR 开发环境配置

正所谓“工欲善其事，必先利其器”。JSAR 的开发环境搭建过程出奇地顺畅，完全是前端开发者熟悉的流程。

第一步：安装 Visual Studio Code

VS Code 是我们的主战场。直接访问 Visual Studio Code 官网下载最新稳定版即可。JSAR 官方推荐 1.80.0 以上版本。

第二步：安装 Node.js

Node.js 是前端工程化的基石。访问 Node.js 官网下载并安装LTS（长期支持）版本。安装后，打开终端（Terminal 或 PowerShell）验证一下：

node -v
npm -v

看到版本号输出，即表示安装成功。

第三步：安装 JSAR DevTools

这是 Rokid 官方为 VS Code 开发的专属插件，提供了诸如“场景视图”预览等核心功能。直接在 VS Code 的扩展市场搜索 JSAR DevTools，点击安装即可，非常便捷。

从 0 到 1：构建我的第一个 AR 项目

环境就绪，让我们马上开始创建项目。

4.1 项目的初始化

JSAR 提供了两种主流的初始化方式，我选择了更快捷的 npm 命令：

通过 npm 创建 (推荐)

在终端中执行以下命令：

npm init @yodaos-jsar/widget

随后，根据命令行提示输入项目名称等信息。该工具会自动从官方模板仓库拉取最新的项目结构。

通过 GitHub Template 创建

你也可以直接访问模板仓库，点击 “Use this template” 按钮来创建一个新的代码仓库。

初始化完成后，进入项目目录，安装必要的依赖：

cd your-project-name
npm install

4.2 解剖 JSAR 项目结构

生成的项目结构非常清晰，核心是两个文件：

package.json：前端项目的“身份证”。它定义了项目名称、版本、依赖库以及构建脚本。我们后续会在这里添加 three.js 等3D渲染库。
main.xsml：JSAR 项目的“空间入口”，类似 Web 开发中的 index.html。它采用 XML 格式来描述 3D 场景的结构，比如模型、光源、脚本等。

4.3 实时预览与调试

JSAR DevTools 提供了强大的本地预览功能：

VS Code 内预览：打开 main.xsml 文件，点击编辑器右上角的 [场景视图] 图标，一个 3D 预览窗口就会出现。任何代码的修改都会自动热更新，开发体验极佳。、

浏览器预览：JSAR 也支持在 Web 浏览器中模拟 AR 效果。首先，我们需要一个本地 Web 服务器：
Bash

# 全局安装一个轻量级服务器
npm install serve -g
# 在项目根目录启动服务
serve -p 8080 --cors

然后，构造一个特定的 URL 访问即可：
https://m-creativelab.github.io/jsar-dom/?url=http://<你的本地IP>:8080/main.xsml

进入后点击【Enter AR】按钮即可模拟Rokid设备中的体验。

5. 我的实践：在现实空间“部署”《三角洲行动》干员“威龙”

告别了 Hello World，我决定将一个更具生命感的对象带入现实：将热门游戏《三角洲行动》中的精英干员“威龙”，通过 AR 技术“部署”到我的桌面上，近距离感受角色的魅力。

5.1 核心逻辑拆解

这次的目标非常纯粹，回归到 AR 展示的本质：

高精度模型加载：在 AR 场景中，稳定、高效地加载并渲染一个带有复杂贴图和材质的 weilong.glb 角色模型。
空间定位与缩放：将角色模型放置在合适的物理表面上，并调整其大小，使其看起来就像一个精致的虚拟手办。
验证加载成功：通过脚本确认模型已经成功渲染到场景中，为后续可能的交互打下基础。

这个实践的核心在于展示 JSAR 处理高质量静态资源的能力。对于许多应用场景，如产品展示、虚拟看展、数字人陈列等，能够逼真地还原模型本身，就是最重要的第一步。

5.2 核心代码展示

我的代码简洁，完美诠释了 JSAR 的“低门槛”。假设你已将角色模型命名为 weilong.glb 并放置在 model 文件夹下。

**package.json** ：

只需确保项目名称和描述更新，以反映新的项目内容。

{
  "name": "jsar-delta-force-weilong",
  "displayName": "Operator Wei Long",
  "version": "1.0.0",
  "description": "An AR display for the character 'Wei Long' from Delta Force.",
  "main": "main.xsml",
  "scripts": {
    "build": "tsc",
    "start": "serve -p 8080 --cors"
  },
  "dependencies": {
    "three": "^0.160.0" 
  },
  "devDependencies": {
    "@types/three": "^0.160.0",
    "typescript": "^5.0.0",
    "serve": "^14.0.0"
  }
}

**main.xsml** - 场景入口文件：

我们通过 <link> 和 <mesh> 标签来定义和实例化模型。

<xsml version="1.0">
  <head>
    <title>JSAR Operator Wei Long</title>
    <link id="weilong-char-model" rel="mesh" type="octstream/glb" href="./model/weilong.glb" />
    <script src="./lib/main.ts"></script>
  </head>
  <space>
    <mesh id="character-weilong" 
          ref="weilong-char-model" 
          selector="__root__" 
          position="0 -0.5 0"
          scale="0.3 0.3 0.3" />
  </space>
</xsml>

我调整了 position 和 scale。position="0 -0.5 0" 稍微下移了模型，使其“脚”部能更好地贴合在识别出的平面上。scale 则将角色缩放为适合桌面的“手办”大小。

**lib/main.ts** ：

import { ARApp, ARMeshNode } from 'jsar-dom';

// 1. 获取在 xsml 中定义的 mesh 节点
const characterNode = ARApp.self.scene.findNodeById('character-weilong') as ARMeshNode;

// 2. 监听 'model-ready' 事件，这是确保模型完全加载并可被访问的最佳时机
characterNode.addEventListener('model-ready', () => {
  // 3. 在浏览器的开发者工具控制台中打印成功信息
  // 这证明我们的模型已成功加载，并且脚本可以与它进行通信
  console.log('《三角洲行动》干员“威龙”已成功部署至 AR 场景！');

  // 本次实践无需添加动画或复杂交互，代码到此为止。
  // 它完美地展示了 JSAR 最纯粹的“加载-显示”核心能力。
});

5.3 运行

编译和运行项目的步骤与之前完全相同。

点击vscode快捷预览：

这次没有复杂的动画，反而让我更能专注于模型本身的质感和 AR 技术带来的“存在感”。这证明了，即便只是简单的静态展示，只要模型足够优秀，AR 就能赋予它全新的生命力，带来远超传统图片和视频的沉浸式体验。

6. 写在最后：我的思考与展望

这次 Rokid JSAR 的开发，远比我预想的要平滑。它真正做到了“让专业的人做专业的事”：

对于前端开发者： 我们无需畏惧陌生的 3D 图形学，只需将 three.js (或者其他 Web 3D 库) 作为一种新的“DOM 操作”工具，将 AR 空间想象成一个无限大的“浏览器窗口”。JSAR 已经为我们铺好了通往这个新世界的红地毯。
低门槛不等于低上限： 虽然入门简单，但 JSAR 的能力远不止于此。结合手势识别、空间持久化、云端锚点等高级功能，完全可以开发出专业级的、富有想象力的 AR 应用。

从网页上的按钮到站立在桌面的虚拟干员，JSAR 为我的开发技能树点亮了一个全新的分支。如果你也是一位对未来充满好奇的前端开发者，不妨也踏上这段 AR 开发之旅，亲自去感受一下在真实世界中“创造”的乐趣。