Cocos2d-x Game Framework

cocos2d-x provides a comprehensive suite of tools for 2D game development, including:

• Scene Management: Workflow and transitions between scenes.
• Graphics & Animation: Sprites, Sprite Sheets, Particle systems, and Skeleton Animations (Spine/Armature).
• Actions: Transformation (Move, Rotate, Scale, etc.), Composable (Sequence, Spawn, Repeat), and Ease actions.
• Physics: Integrated support for Box2d and Chipmunk.
• Input: Touch, Mouse, Keyboard, and Accelerometer support.
• Rendering: OpenGL ES 2.0 (mobile), OpenGL 2.1 (desktop), and Metal (macOS/iOS).

Cocos2d-x does not use C++ exceptions. This prohibition includes exception-related features introduced in C++11, such as noexcept, std::exception_ptr, and std::nested_exception.

Note: There is an exception to this rule for Windows-specific code.

Instead of exceptions, use error codes or assertions to handle failures.

When dynamic allocation is necessary, use ownership logic to manage memory safely.

Best Practices:

• Single Ownership: Prefer having a single, fixed owner for dynamically allocated objects.
• Transfer Ownership: Use std::unique_ptr to make ownership transfer explicit. If other code only needs access, pass a pointer or reference without transferring ownership.
• Shared Ownership: Avoid shared ownership unless there is a significant performance benefit (e.g., avoiding expensive copies of immutable objects). If used, prefer std::shared_ptr<const T>.
• Avoid Legacy Types:
  • Never use linked_ptr or std::auto_ptr.
  • Use std::unique_ptr instead of scoped_ptr (unless maintaining compatibility with older C++ versions).

Example of Explicit Ownership Transfer:

std::unique_ptr<Foo> FooFactory();
void FooConsumer(std::unique_ptr<Foo> ptr);

Multiple inheritance is restricted to specific use cases to avoid complexity:

• Multiple Inheritance: Only allowed if at most one base class has an implementation. All other base classes must be pure interface classes.
• Interface Classes: A class is considered a pure interface if it meets these requirements:
  • It has only public pure virtual (= 0) methods and static methods.
  • It has no non-static data members.
  • It has no constructors, or if it does, they are protected and take no arguments.
  • It must declare a virtual destructor (which should not be pure).
• Naming Convention: Pure interface classes should end with the Interface suffix (e.g., MyClassInterface). This signals to other developers that they should not add implemented methods or non-static data members.

When defining functions, follow this parameter ordering rule:

1. Inputs: values or const references.
2. Outputs/IO: non-const pointers.

Always place all input-only parameters before any output parameters. If you need to add new parameters, do not simply append them to the end if they are inputs; place them before the output parameters to maintain this order.

To avoid polluting the global namespace, prefer using nonmember functions within a namespace or static member functions. Use completely global functions only when absolutely necessary.

• Nonmember functions: Should reside in a namespace and should not depend on external variables.
• Static member functions: Useful when a function is logically tied to a class but does not require a class instance.
• Scope limiting: If a nonmember function is only needed within a specific .cpp file, use an unnamed namespace or static linkage (e.g., static int Foo() { ... }) to limit its scope to that translation unit.

Inline functions allow the compiler to expand the function at the call site rather than using a standard function call mechanism. While they can improve performance for small functions, overuse can increase code size and decrease performance due to instruction cache pressure.

Decision Rules:

• Size Limit: Only define functions inline if they are small (typically 10 lines or less).
• Accessors/Mutators: It is acceptable and common to inline short accessors and mutators.
• Complexity: Avoid inlining functions containing loops or switch statements unless the loop/switch is rarely executed.
• Recursion/Virtual: Recursive functions and virtual functions are typically not inlined by the compiler. Use inline for virtual functions primarily for convenience or to document behavior within the class definition.

Follow these rules for managing class data visibility:

• Private by default: Make data members private.
• Accessors/Mutators: Provide access through accessor functions (e.g., getFoo()) and mutator functions (e.g., setFoo()).
• Naming Convention: Typically, a private variable is named with a leading underscore (e.g., _foo).
• Inlining: Definitions of accessors should usually be inlined in the header file.
• Exception: static const data members (typically named in ALL_CAPS) do not need to be private.

When passing parameters by reference in C++, follow these conventions to ensure clarity and safety:

1. Input Arguments: Use const T& for input parameters. This communicates that the function will not modify the object and that a null value is not expected.
2. Output Arguments: Use pointers (e.g., T* out) for output arguments. This follows the convention that input arguments are values or const references, while output arguments are pointers.
3. When to use const T* instead of const T&: Use a const pointer for input only if:
   • You need to allow a nullptr to be passed.
   • The function needs to save a pointer or reference to the input for later use.
   • You are passing const char* for strings.

Avoid non-const reference parameters unless required by specific conventions like swap().

void foo(const string &in, string *out);