DOCSEARCHbyAlgolia
Submit Docs

Cocos Engine Documentation

repository·v3.8.9·Indexed 27 days ago

https://github.com/cocos/cocos-engine

High-performance runtime framework for the Cocos Creator editor (v3.8.8), supporting 2D and 3D game development across web, native, and instant gaming platforms. Written in C++ and TypeScript, it includes documentation on native build requirements for macOS, iOS, Windows, and Android, WebGPU and Spine WASM compilation, and tools for generating C/C++ bindings via libclang and Swig.

Tokens
61.5K
Snippets
89
Records
491
Agent score
94%

What's inside Cocos Engine

  2. Overview of Cocos Creator Engine

    v3.8.9

    Cocos Engine is the runtime framework for the Cocos Creator editor. It is a high-performance 3D engine designed to provide a complete development workflow with features including:

    • Graphics: GFX implementation supporting WebGL 2 (with WebGL 1 fallback), Vulkan, and Metal.
    • Material System: Based on a custom Effect format using GLSL 300.
    • Core Modules: Lighting, materials, particles, animation (GPU-driven skeletal animation), physics, terrain, UI, sound, and resource/scene node management.
    • Platform Support: Web browsers, Windows, Mac, iOS, Android, HarmonyOS, and mini-game platforms (e.g., WeChat, Facebook Instant Games).
    • Language Support: Primarily implemented in TypeScript, allowing developers to write game logic in TypeScript.

    Note: This engine is primarily designed to be integrated into Cocos Creator and is not intended for standalone use.

  3. Cocos Engine Overview

    v3.8.9

    Cocos Engine is the runtime framework for the Cocos Creator editor, providing 2D and 3D features for cross-platform game development. It supports native platforms (Windows, Mac, iOS, Android, HarmonyOS), web platforms, and instant gaming platforms (Facebook, WeChat, TikTok).

    Key Technical Features

    • Modern Graphics: Uses Vulkan (Windows/Android), Metal (Mac/iOS), and WebGL (Web).
    • High Performance: Core infrastructure (renderer, scene management, native adaptation) is implemented in C++, while the user-level API is provided in TypeScript.
    • Customizable Render Pipeline: Supports built-in forward and deferred pipelines, with full extensibility for custom pipelines.
    • Extensible Surface Shader: Uses an effect format based on GLSL 300 that automatically converts to suitable runtime formats.
    • Physically Based Rendering (PBR): Includes standard effects, physically based cameras, and lighting based on physical metrics.

  6. Understand public and private modules

    v3.8.9

    The Cocos engine uses a module system where visibility is controlled by the /exports directory.

    • Public Modules: Any module located under /exports is considered public. Only bindings explicitly exported from these modules are visible to end-users.
    • Private Modules: Modules that are not under /exports are private. Even if a private module is transitively imported by a public module, its bindings remain inaccessible to users.
    • The 'cc' Module: The 'cc' module is a virtual module that aggregates exports from selected public modules to provide a unified API surface.

  9. System requirements for Cocos Engine native

    v3.8.9

    The following operating systems and versions are supported:

    • macOS: 10.14+
    • iOS: 11.0+
    • iOS Simulator: 13.0+
    • Windows (64-bit): Windows 7+ (Requires Vulkan 1.0 to 1.2 for Vulkan support)
    • Android: 4.4+ (Requires Android 7+ for Vulkan support)

  10. Debug JavaScriptCore (Safari) on macOS and iOS

    v3.8.9

    To debug JavaScriptCore using Safari:

    macOS:

    1. In Safari Preferences -> Advanced, enable Show Develop menu in menu bar.
    2. Entitlements: If your Xcode project lacks an .entitlements file, open the App Sandbox in Capabilities, then close it to auto-generate one. Ensure it is included in Code Signing Entitlements in Build Settings.
    3. Permissions: Open the .entitlements file and add com.apple.security.get-task-allow as a Boolean with value YES.
    4. Signing: In the General tab, select your Developer Certificate.
    5. Run: Compile and run the game. (If using the Creator simulator, you may skip steps 2-5).
    6. Inspect: In the Safari menu, select Develop -> [Your Mac Device Name] -> Cocos2d-x JSB to open the Web Inspector.

    iOS:

    1. On the iPhone, go to Settings -> Safari -> Advanced and enable Web Inspector.
    2. Follow the same Entitlements, Permissions, and Signing steps in Xcode as described for macOS.
    3. Compile and run the game.
    4. In Safari on your Mac, select Develop -> [Your iOS Device Name] -> Cocos2d-x JSB to open the Web Inspector.

  11. Apply internal linkage in .cpp files

    v3.8.9

    When definitions in a .cpp file do not need to be referenced outside that file, provide them with internal linkage. This prevents name collisions with other files.

    How to implement

    • Unnamed Namespaces: Place the code inside namespace { ... }.
    • static keyword: Declare functions or variables as static.

    CRITICAL: Never use unnamed namespaces or static for internal linkage in .h files.

  12. Bind a new module in the Cocos Engine

    v3.8.9

    To add a new C++ module to the Cocos Engine and expose it to the script engine, follow these steps:

    1. Create an interface file: Add a new .i file (e.g., new-engine-module.i) to the native/tools/swig-config directory. Use swig-interface-template.i as a template.
    2. Update Swig configuration: Register the new interface and its corresponding output C++ file in swig-config.js within the configList array.
    3. Generate bindings: Run the generation script from the engine/native/tools/swig-config directory.
    4. Update CMake: Add the generated .cpp and .h files to engine/native/cocos/CMakeLists.txt using the cocos_source_files macro.
    5. Register with Script Engine: Include the generated header and add the registration callback in jsb_module_register.cpp within the jsb_register_all_modules function.