DOCSEARCHbyAlgolia
Submit Docs

LayaAir Engine Documentation

repository·LayaAir_3.4·Indexed 24 days ago

https://github.com/layabox/layaair

LayaAir is a cross-platform 3D engine supporting WebGL, WebGPU, OpenGL, and Vulkan. It enables publishing to web, native apps (Android, iOS, Mac, Windows, Linux), and various mini-game platforms. The engine features a comprehensive IDE for 3D scene, material, particle, blueprint, animation, physics, and UI editing, and includes advanced rendering capabilities such as PBR and Forward+ pipelines.

Tokens
3.7K
Snippets
8
Records
24
Agent score
85%

What's inside LayaAir

  1. Overview of the LayaAir Engine

    LayaAir_3.4

    LayaAir is a cross-platform 3D engine developed by Layabox, designed for games, education, advertising, digital twins, metaverse, AR/VR, and industrial design.

    Key technical features include:

    • Graphics API Support: WebGL, WebGPU, OpenGL, and Vulkan.
    • Rendering Capabilities: Open programmable rendering pipelines, next-generation PBR rendering, ClusterLighting (multi-light technology), and Forward+ rendering pipelines.
    • Multi-Platform Deployment: Supports HTML5 WEB, Native APPs (Android, iOS, HarmonyOS NEXT, Windows, Mac, Linux), and various Mini-Games (WeChat, ByteDance, Alipay, OPPO, vivo, Xiaomi, Taobao, etc.).
    • IDE Integration: Includes editors for 3D scenes, materials, particles, blueprints, animations, physics, and UI. The IDE supports custom workflows via plugins.

  2. Choose the correct LayaAir branch

    LayaAir_3.4

    Select a branch based on your stability and development needs:

    • LayaAir_3.x (e.g., LayaAir_3.1): Stable versions of the LayaAir3 engine.
    • LayaAir_2.x (e.g., LayaAir_2.13.3): Stable versions of the LayaAir2 engine.
    • Master3.0: The active development version of LayaAir3. Do not use this for production environments.

  3. Understand LayaAir engine branches

    LayaAir_3.4

    When working with the repository, choose the appropriate branch based on your needs:

    • LayaAir_3.x (e.g., LayaAir_3.1): Stable versions of the LayaAir 3 engine. Each minor version corresponds to a specific branch.
    • LayaAir_2.x (e.g., LayaAir_2.13.3): Stable versions of the LayaAir 2 engine. Each patch version corresponds to a specific branch.
    • Master3.0: The active development branch for LayaAir 3. Do not use this branch for production environments.

  4. Download the LayaAir IDE

    LayaAir_3.4

    To use the LayaAir engine with its full suite of editors (3D scene, material, particle, blueprint, animation, physics, and UI editors), download the LayaAir IDE directly from the official website. The IDE includes the corresponding engine version.

    https://layaair.com/#/engineDownload

  5. Use a custom-built engine in the IDE

    LayaAir_3.4

    To replace the engine bundled with the IDE with your own custom-built version:

    1. Locate the build/libs folder in your compiled engine directory.
    2. Copy the required .js files from build/libs to your project's engine directory: {Your_Project_Root}/engine/libs.

    You do not need to copy all files; you can selectively overwrite only the specific files you have modified.

  6. Use a custom compiled engine in LayaAirIDE

    LayaAir_3.4

    To use your own compiled version of the engine instead of the one built into the IDE:

    1. Locate the build/libs folder in your compiled engine directory.
    2. Copy the required JavaScript files to your project's engine library directory: {your_project_root}/engine/libs.
    3. You can overwrite specific files rather than copying the entire directory.

  8. Compile the LayaAir Engine from source

    LayaAir_3.4

    If you want to build the engine yourself, follow these steps in the engine root directory:

    1. Install dependencies:

      npm install

    2. Test the engine: Run the following command:

      npm run start

      After running, use a Live Server to open bin/index.html.

    3. Build the engine: Run the following command to generate a build folder containing the compiled engine:

      npm run build
    npm install
npm run start
npm run build

  9. How the Taobao platform adapter handles High Performance Mode

    LayaAir_3.4

    The Taobao platform adapter detects a specific isHighPerformanceMode flag from the environment (my.env.isHighPerformanceMode). This mode changes how file operations and resource loading behave to ensure compatibility with Taobao's native constraints:

    1. File Overwriting: In High Performance Mode, copyFile is not idempotent by default (it may fail if the destination exists). The adapter implements a manual unlink before copyFile to ensure idempotency.
    2. Path Encoding: On iOS in High Performance Mode, local paths used for native resource loading (via readFile or image) must be double-encoded using %2520 (via encodeURI(encodeURI(p))) to ensure the native layer decodes them correctly.
    3. WebGL Configuration: If High Performance Mode is not active, the adapter forces Config.useWebGL2 = false because Taobao's standard mode has incomplete WebGL2 support.
    4. Manifest Handling: For binary manifest files (manifest-<group>.bin) on iOS in High Performance Mode, the adapter converts ArrayBuffer data into a Base64 string prefixed with B64: to bypass Taobao's writeFile limitation regarding ArrayBuffer inputs.

  10. Configure the WeChat Mini Game platform adapter

    LayaAir_3.4

    The WeChat platform adapter for LayaAir is automatically configured via the MgBrowserAdapter lifecycle hooks. This adapter sets up global platform flags and integrates the WeChat (wx) API into the LayaAir Platform Adapter Layer (PAL).

    When the adapter initializes, it performs the following:

    • Sets Browser.onWXMiniGame and Browser.onMiniGame to true.
    • Maps iOS high-performance mode flags from GameGlobal to Browser.
    • Assigns the WeChat global object (window.wx) to PAL.g.
    • Enables willGenerateUndefinedAPIs on the platform global object.
    • Configures PAL.media.videoTextureClass to use WxVideoTexture when running in a non-development environment (i.e., when Browser.onDevTools is false).

  11. Use btJoint as a base for physics joints

    LayaAir_3.4

    In the LayaAir physics engine, btJoint serves as the base class for all physical joints. While you typically use specific joint implementations (like hinge or slider joints), the base class provides the core interface for managing connections between two colliders, setting local anchor points, and handling joint breakage based on force or torque limits.

    Key capabilities provided by the base class include:

    • Connecting Bodies: Use setCollider and setConnectedCollider to define the two objects being joined.
    • Anchor Points: Use setLocalPos and setConnectLocalPos to define the pivot points in the local space of each body.
    • Collision Control: Use isCollision(value: boolean) to enable or disable collision detection between the two linked bodies.
    • Breakage: Set limits using setBreakForce and setBreakTorque. If the applied force or torque exceeds these values, the joint will break (disconnect).
    • State Management: Enable or disable the joint using isEnable(value: boolean) and clean up resources with destroy().

  12. Taobao Platform Adapter Initialization

    LayaAir_3.4

    The Taobao adapter initializes via MgBrowserAdapter.beforeInit. It performs the following setup:

    • Maps the global my object to PAL.g.
    • Normalizes loadSubPackage method names.
    • Sets Browser.isIOSHighPerformanceMode based on my.env.isHighPerformanceMode.
    • Sets Browser.onTBMiniGame = true.
    • Configures MgBrowserAdapter.downloaderClass to use TbDownloader to ensure local paths are correctly encoded for the platform.