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 来全自动处理这一切。
在你的 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）。建议使用简短且易于中文口语识别的名称。
配置完成后，生成原生 iOS 项目：
npx expo prebuild --clean编译并运行你的原生 iOS 项目（确保连接真机或运行在模拟器上）：
npx expo run:ios在 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;成功安装并在真机运行 App 后，iOS 系统会自动注册本库提供的快捷指令动作。
打开 iOS 自带的 「快捷指令 (Shortcuts)」 App，点击右上角 + 新建快捷指令，点击「添加操作」，搜索你的 App 名称或 OSC，你将看到以下两个系统操作：
这是一个智能适配指令。你可以传入一个字符串 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 路径发送自定义数据：
- OSC 地址：例如
/avatar/parameters/myCustomParam - 参数数值：输入布尔值 (
true/false)、浮点数 (如0.85) 或 文本，后台会自动解析对应类型并封包发送。
本库预设了 iOS 的 AppShortcutsProvider，无需手动在快捷指令 App 中配置，安装 App 后即可直接对 Siri 呼叫以下短语（Siri 会自动在后台执行上述操作）：
- "嘿 Siri，用 [应用名] 打开散弹枪"
- "嘿 Siri，用 [应用名] 关闭散弹枪"
- "嘿 Siri，用 [应用名] 开启牛排"
- "嘿 Siri，用 [应用名] 关闭牛排"
例如，如果你的 App 在
app.json中命名为“小工具”，只需说：“嘿 Siri，用小工具打开散弹枪”，你的 VRChat 形象便会实时做出相应动作。
- 请确保你没有直接在 Expo Go 中运行，本库包含原生 Swift 代码，必须通过
npx expo run:ios编译出原生 App。 - 确保在修改配置后重新执行了
npx expo prebuild --clean，以确保 Xcode 项目正确关联并链接了 Pod 依赖。 - 检查编译目标 iOS 版本是否不低于
16.0。
- 网络连通性：确保你的 iOS 真机设备与运行 VRChat 的电脑连接在同一个局域网 (Wi-Fi) 下。
- IP 地址配置：检查在 App 内通过
saveConfig传入的 IP 地址是否与电脑的 IPv4 地址一致，以及端口是否正确（默认9000）。 - VRChat 设置：确保在 VRChat 游戏内的环形菜单 (Radial Menu) -> Options -> OSC 中，OSC 功能已开启 (Enabled)。
- 防火墙阻挡：部分 Windows 防火墙或杀毒软件可能会拦截局域网 UDP 端口，尝试暂时关闭防火墙或将 UDP 9000 端口添加到入站规则白名单。
本项目基于 MIT License 协议开源。