DOCSEARCHbyAlgolia
Submit Docs

Cocos 4 Documentation

repository·v4.0.0·Indexed 23 days ago

https://github.com/cocos/cocos4

A high-performance, cross-platform 2D & 3D game engine using a hybrid C++/TypeScript architecture. This documentation covers native build requirements for macOS, iOS, Windows, and Android, as well as technical guides for compiling Spine WASM, WebGPU native implementations, and using the bindings-generator and swig-config tools for C++ to JavaScript/VM bindings.

Tokens
68.2K
Snippets
91
Records
405
Agent score
77%

What's inside Cocos 4

  1. Overview of COCOS 4

    v4.0.0

    COCOS 4 is an open-source, high-performance, cross-platform game and interactive content development engine. It is built on a C++ architecture and follows a "write once, run anywhere" philosophy.

    In version 4, the engine is being separated from the editor. COCOS refers specifically to the engine, while editor components are being converted to CLI tools integrated into the engine core.

    Key features include:

    • Modern Graphics: Supports Vulkan (Windows/Android), Metal (macOS/iOS), and WebGL (Web).
    • High Performance: Core infrastructure, renderer, and scene management are written in C++.
    • Customizable Render Pipeline: Supports built-in forward and deferred pipelines.
    • Extensible Surface Shader: Uses Cocos's effect format (GLSL 300) with automatic runtime conversion.
    • Physically Based Rendering (PBR): Standard effects include PBR, physically based cameras, and physical lighting metrics.
    • TypeScript API: User-level APIs are provided in TypeScript for efficient development.

  2. Overview of native-pack-tool

    v4.0.0

    The native-pack-tool is a tool customized based on CocosCreator used to integrate standard native platform functional code from a regular CocosCreator build resource folder. It supports rapid compilation and running of corresponding native platform projects.

    To use the tool, your native project directory must follow this structure:

    - build
  - [platform]
    -- data // Original build resource folder
    -- cocos.compile.config.json // Configuration information for all native projects (including project paths, etc.). This file is updated after every build.

  3. Overview of COCOS 4 Engine

    v4.0.0

    COCOS 4 is an open-source, high-performance, cross-platform game and interactive content development engine. It is built on a mature C++ architecture and follows a "write once, run anywhere" philosophy.

    In version 4, the engine is decoupled from the editor. The engine itself is a standalone runtime consisting of modules for lighting, materials, particles, animation, physics, UI, terrain, sound, resources, and scene node management. It supports native platforms (Windows, Mac, iOS, Android, HarmonyOS) and Web browsers, including mini-game platforms like WeChat and Facebook Instant Games.

  7. Select appropriate integer types

    v4.0.0

    Avoid relying on the platform-dependent sizes of standard C++ types like short or long.

    • int: Use for general-purpose integers where you know the value will not be too large (e.g., loop counters). Assume int is at least 32 bits.
    • <cstdint> types: Use precise-width types when size guarantees are required:
      • int16_t, uint16_t, etc.
      • int32_t, uint32_t, etc.
      • int64_t, uint64_t for values that could be $\ge 2^{31}$ (2GiB).
    • Standard types: Use size_t and ptrdiff_t where appropriate.

    Rule of thumb: When in doubt, choose a larger type to avoid overflow during intermediate calculations.

  8. Apply `const` and `constexpr` correctly in APIs

    v4.0.0

    Use of const

    Use const in APIs (function parameters, methods, and non-local variables) whenever it is meaningful and accurate to distinguish reads from writes.

    • Parameters: Use reference-to-const (const T&) or pointer-to-const (const T*) for arguments that a function guarantees not to modify. Do not use const for parameters passed by value.
    • Methods: Declare methods const unless they alter the logical state of the object or cannot be safely invoked concurrently.
    • Placement: Put const first (e.g., const int *foo is preferred over int const *foo).

    Use of constexpr

    Use constexpr to define true constants or to ensure constant initialization. This provides a robust specification of the constant parts of an interface. Avoid using constexpr solely to force inlining.

  9. Prefer structs over pairs and tuples

    v4.0.0

    When elements in a collection or return value have meaningful names, use a struct instead of std::pair or std::tuple. Using named fields is significantly clearer than using .first, .second, or std::get<X>.

    Pairs and tuples should only be used in generic code where elements lack specific meaning, or when required for interoperability with existing APIs.

  10. Use prefix increment and decrement operators

    v4.0.0
    Use the prefix form (++i, --i) of increment and decrement operators unless the code explicitly requires the postfix semantics (where the expression evaluates to the value before modification). Prefix operators are generally more readable and can be more efficient as they avoid making a copy of the value.

  11. Guidelines for using Preprocessor Macros

    v4.0.0

    Avoid defining macros, especially in headers. Prefer inline functions, enums, or const variables. Macros are specifically disallowed for defining pieces of a C++ API because they break refactoring tools and produce confusing compiler errors.

    Best Practices if macros are necessary:

    • Avoid Header Definitions: Do not define macros in .h files. If you must, ensure the name is globally unique by prefixing it with your project's namespace (in UPPERCASE).
    • Local Scope: Define macros immediately before use and #undef them immediately after.
    • Naming: Use a project-specific prefix. Do not use #undef to replace an existing macro; instead, choose a unique name.
    • Avoid Generation: Prefer not using ## to generate function, class, or variable names.

    Preferred Alternatives:

    • Instead of macros for performance: Use inline functions.
    • Instead of macros for constants: Use const variables.
    • Instead of macros for abbreviations: Use references.
    • Instead of macros for conditional compilation: Avoid it where possible to improve testability.
    // BAD: Using macros to define an API
class WOMBAT_TYPE(Foo) {
 public:
  EXPAND_PUBLIC_WOMBAT_API(Foo)
  EXPAND_WOMBAT_COMPARISONS(Foo, ==, <)
};

  12. Handle lifecycle differences between cc::Ref and non-cc::Ref classes

    v4.0.0

    The binding behavior differs depending on whether a class inherits from cc::Ref:

    1. cc::Ref subclasses: The JS object controls the lifecycle of the CPP object. This approach is designed to resolve retain/release issues in the JS layer.
    2. Non-cc::Ref classes: The CPP object controls the lifecycle of the JS object. When the CPP object is destroyed, you must manually notify the binding layer to call clearPrivateData, unroot, and decRef for the corresponding se::Object.

    Safety Tip: When working with non-cc::Ref classes, use cc.sys.isObjectValid in JavaScript to check if the underlying CPP object has been released to avoid illegal logic errors.