# @borndotcom/react-native-godot 中文文档

规范地址：https://npmcn.com/package/%40borndotcom/react-native-godot/

版本：1\.0\.1
npm 元数据更新时间：2025-11-04T07:26:55.286Z
中文译文更新时间：2026-11-08T11:48:24.030Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40borndotcom/react-native-godot
原文对照：https://npmcn.com/package/%40borndotcom/react-native-godot/?lang=original
项目主页：https://github.com/borndotcom/react-native-godot#readme
源码仓库：https://github.com/borndotcom/react-native-godot

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：389 kB，104 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react \*，react-native \*，react-native-worklets-core \*
- 首次发布：2025-11-02T18:11:35.331Z
- 最新版本发布：2025-11-04T07:26:55.074Z
- 近 30 天下载量：1945（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

将 Godot 嵌入回放本地应用程序

## 安装

```sh
npm install @borndotcom/react-native-godot
```

也可以使用：`pnpm add @borndotcom/react-native-godot`、`yarn add @borndotcom/react-native-godot`、`bun add @borndotcom/react-native-godot`

## README

## ![Cover-21](https://github.com/user-attachments/assets/770e4972-84f7-433e-87db-6391601256ba) 原生反应

反应原生哥多特允许将哥多特引擎嵌入回想原生应用程序.

Born React 原生哥多特是创建于 [诞生](https://born.com/) 开发者 [米盖伦](https://migeran.com/)两个小组密切合作.

# 主要特点

-   支持基于Android和iOS的软件 [利布·戈多特(英语:Lib Godot)](https://github.com/migeran/libgodot)。 。 。 .
-   稳定执行,服务数百万用户 [诞生](https://born.com/)其应用.
-   支持开始,停止并重启哥多特引擎. [(文档)](https://npmcn.com/package/%40borndotcom/react-native-godot/#readme-initialize-the-godot-instance)
-   在重启时,可以重新配置引擎,因此每次可以装入不同的Godot应用. [(文档)](https://npmcn.com/package/%40borndotcom/react-native-godot/#readme-stop-the-godot-instance)
-   还有可能暂停并恢复运行中的Godot实例. [(文档)](https://npmcn.com/package/%40borndotcom/react-native-godot/#readme-pause-the-godot-instance)
-   Godot运行在单独的线程上,因此不会影响应用程序的主线程,也不会影响回放原生JavaScript线程. [(文档)](https://npmcn.com/package/%40borndotcom/react-native-godot/#readme-threading-and-javascript-in-react-native)
-   Godot主窗口和由Godot app创建的任何子窗口都可以嵌入在同一屏幕上或单独屏幕上的React Natural应用程序(参见 [示例应用程序](https://npmcn.com/package/%40borndotcom/react-native-godot/example/)) (中文(简体) ).
-   整个Godot API可以从 TypeScript / JavaScript 中访问. 可以将对象、呼叫方法、获得和设置属性、将JS功能附加到信号上、提供JS功能作为Godot方法的可调用功能等. [(文档)](https://npmcn.com/package/%40borndotcom/react-native-godot/#readme-godot-api-usage)

# 从示例应用程序开始

这个 [示例应用程序](https://npmcn.com/package/%40borndotcom/react-native-godot/example/) 显示在动作中反应原生哥多的主要特征.

## 安装先决条件

在开发期间,我们使用 [亚投行](https://asdf-vm.com/) 管理React Independence开发所需的大多数外部依赖,如节点,java,gradle或红宝石. 如果您也使用 ASDF, 请运行 :

```sh
asdf install
```

这将确保所有依赖性都和我们的环境一样。 否则您也可以使用其他方法安装 React 本地先决条件 .

## 导出 Godot 应用程序

为您计划测试的任意一个平台运行以下脚本( 或两者):

```sh
cd example
./export_godot_GodotTest.sh android
./export_godot_GodotTest.sh ios
./export_godot_GodotTest2.sh android
./export_godot_GodotTest2.sh ios
```

脚本的配置是为了在MacOS上的标准系统宽安装文件夹中寻找哥多特. 如果你的Godot安装在别处,或者你在Linux上,请指向GODOT EDITOR 在运行上述脚本之前, 环境变量为您的 GODOT EDITOR :

```sh
export GODOT_EDITOR=/path/to/godot_editor
```

## 配置和下载 Lib Godot

```sh
cd example
yarn
yarn download-prebuilt
```

这些命令将解决国家防范机制的所有反应土著和其他依赖。 第二部将下载GitHub预建的Lib Godot发行版.

## 在 iOS 模拟器上运行

```sh
cd example/ios
bundle install
bundle exec pod install
cd ..
yarn ios
```

## 在 Android 模拟器上运行

```sh
cd example
yarn android
```

## 使用您的本地IDE

您可以使用 Xcode 和 Android Studio 与其它项目相同的方式 。 只要打开:

-   `ios/GodotTest.xcworkspace` 从 X 代码
-   `android` 从Android工作室

注:如果您正在使用ASDF来管理您的java和Node依赖,您应该从反应-native-godot(或例)文件夹下启动Android Studio,从而可以找到这些工具. 例如,在MacOS上:

```sh
cd example
open -a "Android Studio"
```

## 依赖管理的方便脚本

实例应用文件夹中包含一个更新 deps.sh脚本 。 它会在一步内执行所有iOS和Android的设置命令,这样你就可以立即开始工作了.

```sh
cd example
./update_deps.sh
yarn ios # or yarn android
```

# 您的第一个反应原生 Godot App

Born React Independent Godot在国家预防机制上分发.

只要遵循这些步骤, 加入到您的 React 本地应用程序中:

## 更新软件包.json

```sh
yarn add @borndotcom/react-native-godot
```

## 下载预建的 Lib Godot 软件包

React Introduct Godot使用的Lib Godot软件包没有在国家预防机制上分发。 相反,它们通过发布以下命令单独下载:

```sh
yarn download-prebuilt
```

这样React Introduct Godot可以独立于Lib Godot进行更新,同时支持Lib Godot的本地定制建筑.

## 在您的 App 代码中导入回放原生 Godot

```typescript
import { RTNGodot, RTNGodotView, runOnGodotThread } from "@borndotcom/react-native-godot";
```

## 将 Godot 视图添加到您的视图中, 例如 .

```typescript
const App = () => {
    return (
        <View>
            <RTNGodotView style={...}/>
        </View>
    )
};
```

如果没有指定窗口名称属性,则该视图用于Godot的主窗口 .

## 初始化 Godot 实例

我们还将添加 Expo 文件系统模块, 用于从 React Industrial 处理文件系统路径 很简单.

```sh
yarn add expo-file-system
```

```typescript
import * as FileSystem from 'expo-file-system/legacy';

function initGodot() {
  runOnGodotThread(() => {
    'worklet';
    console.log("Initializing Godot");

    if (Platform.OS === 'android') {
        RTNGodot.createInstance(
            ["--verbose", "--path",
            "/main",
            "--rendering-driver", "opengl3",
            "--rendering-method", "gl_compatibility",
            "--display-driver", "embedded"]
        );  
    } else {
        RTNGodot.createInstance(
            ["--verbose", "--main-pack",
            FileSystem.bundleDirectory + "main.pck",
            "--rendering-driver", "opengl3",
            "--rendering-method", "gl_compatibility",
            "--display-driver", "embedded"]
        );  
    }
}
```

有几个事情需要注意:

-   一般的Godot命令行参数可以被传递给初始化函数.
-   使用"嵌入"显示驱动程序是关键,它需要将Godot嵌入回放原生应用程序.
-   可以同时指定目录或包文件.
    -   在Android上,在主包内,包文件内容的访问比访问存储在应用程序的私人区域中的包文件要慢得多. 如果Godot app被存储在主包内,那么它应该作为文件的文件夹被存储在资产文件夹中.
    -   在iOS上,没有这样的限制, 所以我们使用一个包文件在那里.
-   在很多情况下,最好的方法是在运行时下载Godot应用,这有许多优点,包括:
    -   较小的初始应用程序大小
    -   为不同的设备提供专门的应用程序
    -   更新 Godot 应用程序, 不通过整个应用程序审查程序

## 在 App 组件中添加 Godot 初始化

```typescript
const App = () => {
    useEffect(() => {
      initGodot()
      return () => {
      }
    }, [])

    return (
        <View>
            <RTNGodotView style={...}/>
        </View>
    )
};
```

在Hello World app中,当 App 视图显示时,我们只是初始化了 Godot. 看看这个 [示例应用程序](https://npmcn.com/package/%40borndotcom/react-native-godot/example/) 在此存储库中提供一个更详细的例子.

## 停止哥多特事件

为了阻止哥多特事件, 请在哥多特线上拨打RTN哥多特. droy Instance () :

```typescript
function destroyGodot() {
  runOnGodotThread(() => {
    "worklet";
    RTNGodot.destroyInstance();
  });
}
```

注:在停止一个实例后,您可通过拨打RTN Godot来启动一个新的实例。 再次创建Instance。 新实例可以从不同的参数开始,包括其他戈多特项目.

## 暂停哥多特实例

要暂停运行的 Godot 实例, 请在 Javascript 主线上调用 RTN Godot.pause () :

```typescript
RTNGodot.pause();
```

这不会关闭运行中的案例, 只是停止它的执行直到进一步通知.

## 恢复哥多特实例

要恢复已暂停的 Godot 实例, 请在 Javascript 主线上呼叫 RTN Godot. resume() :

```typescript
RTNGodot.resume();
```

## 导出您的 Godot 项目

您可以使用 Godot 引擎的通常导出功能, 只要确保导出到 PCK 或 ZIP 而不是整个应用程序 .

在反应原生哥多特实例应用程序中 `export_godot.sh` 和一个关联 `export_godot_GodotTest.sh` 提供了脚本,可以使导出过程更加容易.

要将您的工程导出至iOS或Android,请使用包含以下参数的我们导出 godot.sh脚本:

```
--target: Base directory where the project will be exported. Depending on the platform a pck file or a folder will be created here.
--project: The directory of the project that will be exported.
--name: The name of the exported project.
--preset: The export preset to be used.
--platform: The platform to export the project to (iOS or Android).
```

注释:

-   Android项目将导出为项目文件夹,而iOS项目将导出为PCK文件.
-   默认情况下, export godot.sh 将在应用程序文件夹下寻找正式的 Godot 安装 。 如果您的安装在其他地方, 或者您想要使用自定义的 Godot 构建, 请指定它位于 GODOT EDITOR 环境变量中 .

# Godot API 使用法

在导入React Endern Godot后,可以通过RTN Godot类访问Godot API.

## 获取 API 切入点

要访问 Godot API, 请先拨打 RTN Godot. API ():

```typescript
let Godot = RTNGodot.API();
```

## 访问 Singletons

从入站点可以得到引擎的单子:

```typescript
// Get Godot's Engine singleton.
let Godot = RTNGodot.API();
var engine = Godot.Engine;
```

## 证明对象

您可以使用定义的构造器即时化 Godot API 对象 :

```typescript
var vector = Godot.Vector2();
```

## 访问属性

对象属性可以直接访问 :

```typescript
var vector = Godot.Vector2();
vector.x = 1.0;
vector.y = 2.0;
```

## 调用方法

Godot API 方法也可以称为:

```typescript
let Godot = RTNGodot.API();
var engine = Godot.Engine;

// Call Godot API methods:
var sceneTree = engine.get_main_loop();
var root = sceneTree.get_root();
// NOTE: From here you can access nodes of the scene tree and manipulate them from TypeScript.
```

## 附着于信号

JS功能可以连接到哥多信号:

```typescript
let Godot = RTNGodot.API();

var button = Godot.Button();
button.set_text("Button");

button.pressed.connect(function() {
  console.log("Button pressed.")
})
```

## 向戈多特传递联署文件

JS功能可以传递给戈多特方法用作可调用:

让我们创建一个自定义的 RN Interface 节点,并添加到 Godot 项目的场景树上. GDScript应该读作:

```gdscript
extends Node
class_name RNInterface

func test_callable(c: Callable) -> void:
    c.call("Hello from Godot")

```

从 TypeScript 可以使用以下代码片段访问它 :

```typescript
let Godot = RTNGodot.API();
var engine = Godot.Engine;
var sceneTree = engine.get_main_loop();
var root = sceneTree.get_root();

var iface = root.find_child("RNInterface", true, false)

iface.test_callable(function(s: string) {
  console.log("Received text from Godot: " + s)
}); 
```

## 本地反应中的线索和 JavaScript

在React Industrial app中,JavaScript主线程,其中应用程序所运行的JavaScript代码大部分与Android或iOS应用的主线程相分离.

这样JS Thread的处理不会影响主应用程序UI. 遵循同样的模式,哥多特引擎也运行在自己的线程上,它与应用程序的主JavaScript线程和React Induct主JavaScript线程都分开. 由于JavaScript是按设计单行的,为了能够从JavaScript与Godot线程进行通信,我们使用熟知的 [反应-本土-工作-核心](https://github.com/margelo/react-native-worklets-core) 库,它允许我们运行 JS 代码 在哥多线程 使用工作板.

Worklets是 JavaScript 函数,指定了"Worklet"关键词.

```typescript
function worklet() {
    'worklet'
}
```

这些功能及其所有外部依赖性被转换成自封的联署材料捆绑,从而可以在单独的联署材料中执行。 欲了解更多信息,请参见: [反应原生工地 核心文件](https://github.com/margelo/react-native-worklets-core/blob/main/docs/USAGE.md)。 。 。 .

React Introduct Godot 提供了一个名为帮助器的函数 `runOnGodotThread()` 这将允许您执行 _已工作_ JS在戈多线上发挥作用.

一般来说,这是与哥多特引擎互动的推荐方式,如我们的例子应用所示.

虽然可以直接从主反应原生线与Godot引擎交互,但有一些警告,一般不建议:

-   从"哥多特引擎"的观点来看,这种引用会在"背景"线条上被执行,也就是说,例如,Scene Tree不能直接从这个线条上完全访问. 关于戈多特语背景线条如何工作的更多信息,请参见其 [文档](https://docs.godotengine.org/en/stable/tutorials/performance/thread_safe_apis.html)。 。 。 .
    
-   Godot反对在主要联署材料线索和工作场所获得的参考材料,因为它们与不同的联署材料相关联。 有可能创建可在多个JS背景下工作的对象引用,但这些引用会增加运行时间的间接费用,目前没有在React Independent Godot中支持. 如果您在申请中需要此功能, 请联系 [米盖伦](https://migeran.com/contact) 详细讨论你的要求.
    

# 高级主题

## 使用自定义的 Lib Godot 构建

1.  要使用自定义 Lib Godot 构建, 您首先需要克隆 [Lib Godot 项目](https://github.com/migeran/libgodot) 在树枝上 `libgodot_migeran_45`,包括其所有子模块.
    
    ```sh
    git clone --recursive https://github.com/migeran/libgodot -b libgodot_migeran_45
    ```
    
2.  然后从源头建立 Lib Godot :
    
    ```sh
    cd libgodot
    ./build_prebuilt_release.sh   # for release libraries
    # OR
    ./build_prebuilt_dev.sh   # for development libraries
    ```
    
    注:如果只建一个站台,您可以评论构建脚本中不必要的行.
    
    在进程结束时,将在 `build/prebuilt/release` 或 `build/prebuilt/dev` 文件夹.
    
3.  建成完成后,设置这些环境变量:
    
    ```sh
    export LIBGODOT_XCFRAMEWORK_PATH=path/to/libgodot/build/prebuilt/release or dev/libgodot.xcframework.zip 
    export LIBGODOT_CPP_XCFRAMEWORK_PATH=path/to/libgodot/build/prebuilt/release or dev/libgodot-cpp.xcframework.zip
    export LIBGODOT_ANDROID_PATH=path/to/libgodot/build/prebuilt/release or dev/libgodot-android.zip
    export LIBGODOT_CPP_ANDROID_PATH=path/to/libgodot/build/prebuilt/release or dev/godot-cpp-android.zip
    export SHASUM_CHECK=false
    export REPLACE_EXISTING=true
    ```
    
    这些环境变量凌驾于反应-内存-godot的下载预建脚本的下载逻辑:
    
    -   使用本地显示的文件来代替套件中指定的 URL.json of reaction-native-godot.
    -   不要检查所提供的SHA-256散列.
    -   强制替换已安装的库, 即使已经安装同一版本 .
4.  然后运行下载预建的脚本以安装自定义已建库:
    
    ```sh
    yarn download-prebuilt
    ```
    
    注:这个脚本的一个实例用法见于我们的例子/update deps.sh脚本.
    
5.  在Android上,如果使用开发构建,则在反应-自制-godot/android/build.gradle the 后面的行需要更新以包含 `godot-dev` 作为文物:
    
    ```groovy
    api "com.migeran.libgodot:godot:${libGodotVersion}-SNAPSHOT"
    ```
    

## 调试本地 Godot 代码

要调试本地引擎代码( C++), 您首先需要构建并安装上述 Lib Godot 的开发版本 .

在iOS上,这允许您在Xcode中将断点设置入Godot引擎本身,并像自己的应用一样轻松地调试.

根据 Xcode 版本,您可能需要在 Xcode 中单独打开这些文件,然后将编辑器从新窗口移动到窗口中您的应用程序的 Xcode 项目.

Android上还需要几个步骤:

-   在Android Studio Run/Debug配置中,您还需要添加一个符号目录,其中为libgodot android. 因此,包含的调试符号被定位。 一个好地方是: `path/to/libgodot/godot/platform/android/java/lib/libs/dev/arm64-v8a`。 。 。 .
    
-   取决于Android Studio版本,你可能需要在Android Studio项目下将Godot源树包含在内,才能设置断点. 这样做的一种方法是在React Independent Godot 库下建立一个符号链接如下:
    

```sh
cd /path/to/your/app/node_modules/@borndotcom/react-native-godot/android/src/main/cpp
ln -s /path/to/libgodot/godot godot
```

-   然后再将项目 / 重新将 Gradle 项目文件导入Android Studio.

## 在 Godot 编辑器中调试 Godot 项目

### 机器人

1.  对于远程调试,您首先需要构建并安装上述Lib Godot的开发版本.
    
2.  然后在您的 RTNGodot 中添加这两个额外的参数 。 创建Instance 呼叫 :
    
    ```typescript
    '--remote-debug',
    'tcp://127.0.0.1:6007'
    ```
    
3.  为了在你的Android设备上曝光TCP端口6007,通过你的计算机上的TCP端口6007,打开一个终端并呼叫:
    
    ```sh
    adb reverse tcp:6007 tcp:6007
    ```
    
    注: 每次断开并重新连接设备时,都需要再次调用此设备 .
    
4.  现在您可以在"哥多特"编辑器中打开您的项目. 首先启用“ 调试” - > “ 调试服务器打开” , 然后设置断点 。 您也可以在应用程序运行时设置断点 .
    
5.  一旦设定出断点,您可以通过从Android Studio启动您的应用程序来开始调试.
    

### iOS系统

1.  对于远程调试,您首先需要构建并安装上述Lib Godot的开发版本.
    
2.  打开 Godot 编辑器, 然后转到 “ godot ” - > “ 编辑器设置 ” - “ 网络” - “ 调试” - “ 调试主机 ” , 并设置您的 Mac 的 IP 地址 .
    
3.  还启用“ 调试” - > “ 保持调试服务器打开 ” .
    
4.  然后在您的 RTNGodot 中添加这两个额外的参数 。 创建Instance 呼叫 :
    
    ```typescript
    '--remote-debug',
    'tcp://<your_macs_ip_address>:6007'
    ```
    
5.  现在,你可以开始调试,从Xcode启动你的应用程序. 您可以在运行应用程序之前或运行时设置断点 .
    

注:您的Mac和您的iOS设备必须连接到同一个网络/路由器上才能建立连接.

# 诞生

我们已在柏林和纽约开设了新职位! 我们正寻找最优秀的反动原生工程师.

看看我们的开口: [(原始内容存档于2018-10-21). born.com](https://born.com/)

# 商业支助和发展

[米盖伦](https://migeran.com/) 提供商业支持和发展服务, [利布·戈多特(英语:Lib Godot)](https://github.com/migeran/libgodot) 还有哥多引擎. [从这里开始](https://migeran.com/contact) 描述你的要求.

# 许可证

Born React Introduct Godot根据麻省理工学院的许可发布.

## 常见问题

### @borndotcom/react-native-godot 是什么？

将 Godot 嵌入回放本地应用程序

### 如何安装 @borndotcom/react-native-godot？

在项目目录运行 npm install @borndotcom/react-native-godot，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）、react-native（\*）、react-native-worklets-core（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 download-prebuilt，可以用 npx download-prebuilt 直接运行。

### @borndotcom/react-native-godot 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @borndotcom/react-native-godot 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @borndotcom/react-native-godot 可以商用吗？

@borndotcom/react-native-godot 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @borndotcom/react-native-godot 的下载量有多少？

根据 npm 官方下载统计，@borndotcom/react-native-godot 在 2026/10/09 – 2026/11/07 这 30 天内被下载 1,945 次，日均约 65 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @borndotcom/react-native-godot 还在维护吗？

最新版本 1\.0\.1 发布于 2025/11/04（1 年前）；至今共发布 2 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/11/03。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。