expo-vrc-osc-intent

English | 简体中文

expo-vrc-osc-intent 是一个专为 Expo (SDK 54+) 打造的原生模块，支持在 iOS 16+ 设备上通过 Siri 语音 或 苹果快捷指令 (Siri Shortcuts / App Intents) 以后台进程方式向 VRChat 发送 UDP OSC 消息。

通过该库，用户无需让 App 保持前台，即可在锁屏、打游戏甚至息屏状态下，通过 Siri 声控或 iOS 快捷指令触发 VRChat 中的虚拟形象参数（如开关武器、控制道具、发送 Chatbox 聊天文本等）。

🌟 特性

• ⚡️ iOS 原生 App Intents 支持：利用 iOS 16+ 最新的 AppIntent 架构，直接集成入系统「快捷指令」App。
• 🗣 Siri 语音声控：预设系统语音短语，可直接通过 "嘿 Siri，用 [应用名] 打开散弹枪" 发送指令。
• 📱 纯后台运行：通过快捷指令触发时无需唤醒 App 前台，极低延迟，瞬间完成 UDP OSC 封包发送。
• 🔌 Expo 插件驱动：提供 Expo Config Plugin，在 expo prebuild 时自动处理原生项目配置（包含文件注入、编译源关联及 Deployment Target 设置）。
• 🛠 自定义扩展：既支持内置的高频预设指令，也提供了通用的「发送自定义 OSC 消息」快捷指令动作，可传递布尔、浮点数或字符串。

📦 安装

请在你的 Expo 项目根目录下运行：

npx expo install expo-vrc-osc-intent

⚙️ 配置与预构建

本库依赖 iOS 16+ 的 App Intents 机制，需要在原生项目中注入自定义 Swift 文件。我们提供了 Config Plugin 来全自动处理这一切。

1. 配置 app.json

在你的 Expo 项目的 app.json 中，将本库添加到 plugins 列表中：

{
  "expo": {
    "name": "你的应用名称",
    "slug": "你的应用标识",
    "ios": {
      "bundleIdentifier": "com.yourname.vrcosc",
      "supportsTablet": true
    },
    "plugins": [
      "expo-vrc-osc-intent"
    ]
  }
}

[!IMPORTANT] 注意：Siri 快捷指令会使用 app.json 中的 name 作为系统语音识别的前缀（即 applicationName）。建议使用简短且易于中文口语识别的名称。

2. 执行 Prebuild 预构建

配置完成后，生成原生 iOS 项目：

npx expo prebuild --clean

编译并运行你的原生 iOS 项目（确保连接真机或运行在模拟器上）：

npx expo run:ios

🚀 API 使用指南

在 React Native / Expo 前端，你需要调用 saveConfig 方法来配置 VRChat 运行所在的局域网 IP 地址和 OSC 端口（VRChat 默认 OSC 端口为 9000）。这些信息将被持久化到系统的 UserDefaults 中，供后台快捷指令进程读取。

import React, { useEffect } from 'react';
import { StyleSheet, Text, View, Button } from 'react-native';
import ExpoVrcOscIntent from 'expo-vrc-osc-intent';

export default function App() {
  useEffect(() => {
    // 保存 VRChat 运行电脑的局域网 IP 与 OSC 端口
    // 快捷指令后台进程会自动读取该配置进行 UDP 发送
    ExpoVrcOscIntent.saveConfig("192.168.1.100", 9000);
  }, []);

  return (
    <View style={styles.container}>
      <Text style={styles.title}>VRChat OSC 控制台</Text>
      <Button 
        title="更新 OSC 配置" 
        onPress={() => ExpoVrcOscIntent.saveConfig("192.168.1.100", 9000)} 
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, justifyContent: 'center', alignItems: 'center', backgroundColor: '#eee' },
  title: { fontSize: 20, marginBottom: 20 },
});

接口定义

/**
 * 保存局域网 OSC 配置。
 * @param address VRChat 所在的局域网 IP 地址（例如 "192.168.3.15"）
 * @param port OSC 监听端口（VRChat 默认是 9000）
 */
function saveConfig(address: string, port: number): void;

🎙 iOS 快捷指令与 Siri 声控

成功安装并在真机运行 App 后，iOS 系统会自动注册本库提供的快捷指令动作。

1. 自定义快捷指令 (Shortcuts App)

打开 iOS 自带的 「快捷指令 (Shortcuts)」 App，点击右上角 + 新建快捷指令，点击「添加操作」，搜索你的 App 名称或 OSC，你将看到以下两个系统操作：

🔹 操作一：发送 OSC 捷径指令 (SendOscIntent)

这是一个智能适配指令。你可以传入一个字符串 command，它会进行以下匹配：

| 传入参数 (command) | 对应的 VRChat OSC 地址 & 参数 | 说明 | | :--- | :--- | :--- | | opengun / 打开散弹枪 | /avatar/parameters/Tri_PunisherZenith_Weapon_off (false) /avatar/parameters/Tri_PunisherZenith_grab_on (true) | 预设动作：开启枪械武器 | | closegun / 关闭散弹枪 | /avatar/parameters/Tri_PunisherZenith_Weapon_off (true) /avatar/parameters/Tri_PunisherZenith_grab_on (false) | 预设动作：收回枪械武器 | | steak / 打开牛排 / 吃牛排 | /avatar/parameters/steak (true) | 预设动作：触发食物道具 | | nosteak / 关闭牛排 / 别吃牛排 | /avatar/parameters/steak (false) | 预设动作：收回/关闭道具 | | 其他任意文本 (如 "你好") | /chatbox/input (文本内容, true, true) | 自动发送至 VRChat 聊天框，并在游戏中气泡显示 |

🔹 操作二：发送自定义 OSC 消息 (SendCustomOscIntent)

向指定的 OSC 路径发送自定义数据：

• OSC 地址：例如 /avatar/parameters/myCustomParam
• 参数数值：输入布尔值 (true/false)、浮点数 (如 0.85) 或 文本，后台会自动解析对应类型并封包发送。

2. Siri 语音直接声控

本库预设了 iOS 的 AppShortcutsProvider，无需手动在快捷指令 App 中配置，安装 App 后即可直接对 Siri 呼叫以下短语（Siri 会自动在后台执行上述操作）：

• "嘿 Siri，用 [应用名] 打开散弹枪"
• "嘿 Siri，用 [应用名] 关闭散弹枪"
• "嘿 Siri，用 [应用名] 开启牛排"
• "嘿 Siri，用 [应用名] 关闭牛排"

例如，如果你的 App 在 app.json 中命名为 “小工具”，只需说：“嘿 Siri，用小工具打开散弹枪”，你的 VRChat 形象便会实时做出相应动作。

⚠️ 常见问题与排查 (FAQ)

Q: 提示 Cannot find native module 'ExpoVrcOscIntent'？

1. 请确保你没有直接在 Expo Go 中运行，本库包含原生 Swift 代码，必须通过 npx expo run:ios 编译出原生 App。
2. 确保在修改配置后重新执行了 npx expo prebuild --clean，以确保 Xcode 项目正确关联并链接了 Pod 依赖。
3. 检查编译目标 iOS 版本是否不低于 16.0。

Q: 快捷指令发送了，但 VRChat 游戏内没有任何反应？

1. 网络连通性：确保你的 iOS 真机设备与运行 VRChat 的电脑连接在同一个局域网 (Wi-Fi) 下。
2. IP 地址配置：检查在 App 内通过 saveConfig 传入的 IP 地址是否与电脑的 IPv4 地址一致，以及端口是否正确（默认 9000）。
3. VRChat 设置：确保在 VRChat 游戏内的环形菜单 (Radial Menu) -> Options -> OSC 中，OSC 功能已开启 (Enabled)。
4. 防火墙阻挡：部分 Windows 防火墙或杀毒软件可能会拦截局域网 UDP 端口，尝试暂时关闭防火墙或将 UDP 9000 端口添加到入站规则白名单。

📄 开源协议

本项目基于 MIT License 协议开源。