DOCSEARCHbyAlgolia
Submit Docs

PuerTS Documentation

repository·master·Indexed 27 days ago

https://github.com/tencent/puerts

A multi-language scripting solution for Unity, Unreal Engine, and .NET. PuerTS enables high-performance interop with JavaScript/TypeScript, Lua, and Python. It provides a JavaScript runtime for game engines with support for static type checking, reflection binding, and various backends including V8, QuickJS, and Node.js. The solution includes the Puerts.Agent framework for AI capabilities in Unity and supports platforms including Windows, macOS, Linux, iOS, and Android.

Tokens
96.6K
Snippets
215
Records
504
Agent score
91%

What's inside PuerTS

  1. Overview of PuerTS for Unreal Engine

    master

    PuerTS is a TypeScript programming solution designed for game engines. It provides a JavaScript runtime that allows TypeScript to access the host engine through module-binding at the JavaScript level and the automatic generation of TypeScript declarations.

    Key benefits include:

    • Improved Robustness: Unlike Lua, TypeScript supports static type checking, enhancing code maintainability.
    • High Efficiency: Supports reflection binding across the platform, eliminating the need for manual code generation during development.
    • High Performance: Supports static binding for handling complex scenes.
    • WebGL Support: Offers significantly faster performance in WebGL environments compared to Lua.
    • Toolchain Integration: Combines professional engine rendering power with the vast ecosystem of JavaScript packages and toolchains.

  2. Overview of Unity Editor Assistant

    master

    The Unity Editor Assistant is a Puerts.AI tool that allows you to control the Unity Editor using natural language. It generates and executes JavaScript code within the PuerTS environment, providing full access to UnityEngine.* and UnityEditor.* APIs.

    Key capabilities include:

    • Scene Building: Creating GameObjects, adjusting Transforms, and assigning materials via text commands.
    • Log Analysis: Filtering and summarizing PuerTS-related logs.
    • Scene Health Checks: Detecting missing scripts or other issues by traversing GameObjects.
    • Direct API Access: Performing any operation possible via C# scripts.

  3. Overview of PuerTS for Unreal

    master
    PuerTS for Unreal is a solution that allows developers to interact with Unreal Engine using TypeScript. It provides high-performance access to Unreal Engine's core features without requiring manual glue code generation for Blueprint interfaces. It supports both reflection-based binding and static code-based binding for optimized performance.

  4. Understand the relationship between FJsEnv, Mixin, and Class Extension

    master

    Understanding how PuerTS components interact is crucial for architecture:

    • puerts::FJsEnv: A standalone virtual machine instance. Data is isolated between different instances.
    • Blueprint Mixin: A feature available to any puerts::FJsEnv instance.
    • Extend Engine Classes: A high-level feature built on top of puerts::FJsEnv. It requires a default puerts::FJsEnv to manage the proxy Blueprints. Note that this default environment is isolated from any other puerts::FJsEnv instances you manually create.

  5. Explore PuerTS Community Scaffolding and Frameworks

    master

    The PuerTS community provides several CLI tools, frameworks, and libraries to assist with development, including scaffolding and secondary wrappers for Unity.

    CLI Tools & Frameworks:

    • puerts_cli by @sbfkcel
    • puerts-unity-kit by @throw-out
    • Nice-TS by @Justin-sky
    • puerts-starter-kit by @Geequlim
    • puerts-component by @zgz682000
    • UnityTs by @jungog
    • puerts-ts-loader by @zombieyang

  6. Explore PuerTS Commercial Support Plans

    master

    PuerTS offers two tiers of commercial support for developers seeking advanced services beyond the open-source version. These plans include technical consulting, performance analysis, legacy version support (PuerTS 1.3 and below, Unity 2018 and below), and access to non-open-source technical features.

    1. Advanced Plan (高级计划)

    Includes:

    • Unlimited technical Q&A and JS ecosystem training.
    • Project performance analysis and troubleshooting.
    • Access to upcoming/non-open-source features like v8 Snapshot optimization, bytecode support, pointer compression, and pixui.
    • Priority access to features like fast-c-api call, cross-language Buffer suites, and WebGL multi-threading components.
    • Full-link technical services for Mini-Games (QuickJS-based hot updates, loading speed optimization).
    • Technical assistance for ecosystem libraries (e.g., puerts-unity-kit, puerts-starter-kit, puerts-cli, nice-ts).

    2. Premium Plan (特级计划)

    Includes everything in the Advanced Plan, plus:

    • Custom feature development tailored to your project's specific requirements.
    • Support for Non-Disclosure Agreements (NDA) to ensure code privacy.

  7. Compare PuerTS JavaScript Backends

    master

    PuerTS supports three different JavaScript engines. Choose the one that best fits your requirements for performance, binary size, and API support:

    • V8 (Recommended): Best overall performance and moderate binary size. Supports ECMAScript spec only (no Node API).
    • Node.js: Provides full Node.js API support but has the largest binary size. High performance.
    • QuickJS: Smallest binary size, ideal for size-sensitive scenarios, but lower performance and no Node API.

  8. Understand the P-API Plugin Architecture

    master

    PuerTs uses a unified scripting engine abstraction interface called P-API (Portable Embedded Scripting API, or pesapi). This allows the Unity C# layer to interact with various scripting engines (V8, QuickJS, Lua, Python, etc.) through a consistent interface without needing to know the specific engine implementation.

    Key Components

    ComponentDescription
    PuertsCoreA shared core library defining the pesapi.h abstract interface and the ScriptClassRegistry class registration system. All language plugins link against this.
    PesapiXxxImplThe core implementation that fulfills the pesapi_ffi function table, mapping generic pesapi operations to specific engine APIs.
    CppObjectMapperManages the mapping between C# objects and script objects, handling caching, lifecycle tracking, and type templates.
    PapiExportProvides exported C functions that the C# layer calls to perform tasks like creating/destroying environments or retrieving the FFI table.
    BackendEnv(Optional) Manages the lifecycle of the script engine, such as runtime initialization and module loading.

  9. Understand JIT performance advantages in WebGL

    master

    When publishing Unity games to the WebGL platform, PuerTS provides a significant performance advantage over Lua-based solutions (like xLua) due to how it handles script execution.

    While Lua scripts in WebGL are typically executed within a compiled WASM virtual machine (which cannot utilize the browser's JIT capabilities), PuerTS sends JavaScript scripts directly to the browser's native JS environment. This allows the scripts to leverage the browser's built-in JIT (Just-In-Time) compiler, resulting in execution speeds that can be orders of magnitude faster than running scripts inside WASM.

  10. Choose a PuerTS JS Engine Backend

    master

    PuerTS supports three different JavaScript engine backends depending on your requirements:

    • NodeJS: The default backend (used by OpenUPM). It provides powerful APIs for files and networking, allowing seamless use of the npm ecosystem. Recommended if you need to use npm packages.
    • V8: A classic, high-performance choice. It is highly debuggable and has a moderate footprint.
    • QuickJS: Extremely small footprint. However, it does not support debugging or JIT. Use this if you need to minimize the final installation package size.

  11. Understand PuerTS performance modes and benchmarks

    master

    PuerTS performance varies based on the interop mode and whether StaticWrappers are used. When evaluating interop performance (especially for structs), subtract the C# API consumption time from the total time to get the true interop cost.

    Performance Modes

    • Puer S: Not using xIl2cpp mode, but with StaticWrapper generated.
    • Puer X R: Using xIl2cpp mode, but without xIl2cpp StaticWrapper (uses Reflection).
    • Puer X S: Using xIl2cpp mode, and with xIl2cpp StaticWrapper generated.

    General Performance Characteristics

    • Android: Interop performance is approximately twice that of xLua. Self-execution is faster than xLua due to PuerTS's engine capabilities and is comparable to C# performance.
    • iOS: Interop performance is on par with xLua (slightly slower with primitive types/no parameters, slightly faster with object parameters). Self-execution is on the same level as xLua.

  12. Compare Agent Mode vs MCP Mode for Unity Editor Assistant

    master

    The Unity Editor Assistant supports two distinct modes depending on your workflow:

    FeatureAgent Mode (Built-in)MCP Mode (External)
    UPM Packagecom.tencent.puerts.agentcom.tencent.puerts.mcp
    InterfaceDirect chat window inside UnityConnect via MCP-compatible tools (Cursor, Windsurf, Claude Desktop)
    Speed⚡ Faster (local script execution)Slower (requires HTTP communication)
    CollaborationIndependent Unity operations🤝 Syncs with code editors (AI edits code and controls Unity simultaneously)
    Best ForScene building, quick prototypingVibe coding, deep code-editor/Unity integration