node-raylib

The node-raylib generator uses ToValue and FromValue patterns to bridge C++ raylib types with Node.js (N-API) objects.

• ToValue: Converts a C++ struct or primitive into a JavaScript-compatible Napi::Value. For example, a Vector2 is converted into a JavaScript object with x and y properties, while primitives like float and int are converted to Napi::Number.
• FromValue: Extracts C++ types from Napi::CallbackInfo. These functions typically take a reference to an index to track the current position in the argument list as they consume values from the JavaScript call.

// Example of converting a C++ struct to a JS Object
Napi::Value ToValue(napi_env env, Vector2 obj) {
  Napi::Object out = Napi::Object::New(env);
  out.Set("x", ToValue(env, obj.x));
  out.Set("y", ToValue(env, obj.y));
  return out;
}

// Example of extracting a C++ struct from JS arguments
Vector2 Vector2FromValue(const Napi::CallbackInfo& info, int& index) {
  return (Vector2) {
    FloatFromValue(info, index += 1),
    FloatFromValue(info, index += 1)
  };
}

To achieve high performance, node-raylib uses a technique called argument flattening.

In standard Node.js native addons, passing a JavaScript object to represent a C++ struct (like Texture2D or Color) is extremely expensive because the C++ layer must parse the object properties at runtime.

To avoid this, node-raylib flattens these structs into a long list of individual primitive arguments (numbers, booleans, etc.) before they reach the C++ layer. This allows the native side to construct the C++ structs directly from the argument list without expensive object lookups, which can result in significantly higher framerates (up to 6x faster in benchmarks).

How it affects API usage

When calling the underlying native raylib object directly, you cannot pass objects. Instead, you must pass the individual properties of those objects in the specific order required by the flattened binding.

However, for ease of use, the library also provides wrapper functions that allow you to use the standard raylib API (passing objects like Texture or Color) by automatically flattening them for you before calling the native layer.

// Standard raylib API usage (via wrappers):
raylib.DrawTexture(myTexture, 10, 10, myTextureColor)

// Underlying native call (flattened):
raylib.DrawTexture(
    myTexture.id, myTexture.width, myTexture.height, myTexture.mipmaps, myTexture.format,
    10, 10,
    myTextureColor.r, myTextureColor.g, myTextureColor.b, myTextureColor.a
)

You can record and play back user input sequences using automation events.

1. Load/Export: Use LoadAutomationEventList(fileName) to load a list from a file or ExportAutomationEventList(list, fileName) to save a list to a text file.
2. Setup: Before recording, you must set the list to record into using SetAutomationEventList(list) and optionally set the starting frame with SetAutomationEventBaseFrame(frame).
3. Recording: Call StartAutomationEventRecording() to begin and StopAutomationEventRecording() to end.
4. Playback: Use PlayAutomationEvent(event) to play a specific AutomationEvent.

// Example workflow
const list = LoadAutomationEventList("my_events.txt");
SetAutomationEventList(list);
SetAutomationEventBaseFrame(0);

StartAutomationEventRecording();
// ... perform actions ...
StopAutomationEventRecording();

ExportAutomationEventList(list, "recorded_actions.txt");

To optimize performance, certain raylib structs (like Texture) are cached in C++ memory rather than being copied back and forth between JavaScript and C++ for every function call.

When you load such a struct, the C++ binding allocates space in a memory pool and returns a JavaScript object containing the struct's data and a hidden pointer property. This pointer is a 64-bit integer representing the memory address in C++.

Key Concepts:

• Performance: Passing a single integer (the pointer) to C++ functions is significantly faster than copying large data structures.
• Scope: Only structs with explicit Load() and Unload() functions in the raylib API (e.g., Texture) use this mechanism. Small, transient structs like Color or Rectangle are passed by value (copied) and do not use pointers.
• Memory Management: Because these structs live in C++ memory, they are not managed by the JavaScript garbage collector. You must manually unload them to prevent memory leaks.

Raylib uses a state-based approach for drawing. You must wrap drawing operations in specific Begin and End functions to switch between different rendering contexts like 2D, 3D, textures, or shaders.

Core Drawing Lifecycle

• BeginDrawing(): Prepares the canvas (framebuffer) to start a new frame of drawing.
• EndDrawing(): Finalizes the drawing and performs buffer swapping (double buffering) to display the frame on screen.
• ClearBackground(color): Clears the entire framebuffer with a specific Color.

Specialized Drawing Modes

• 2D Mode: Use BeginMode2D(camera) and EndMode2D() to draw using a Camera2D transform.
• 3D Mode: Use BeginMode3D(camera) and EndMode3D() to draw using a Camera3D transform. EndMode3D() returns the context to default 2D orthographic mode.
• Render Textures: Use BeginTextureMode(target) and EndTextureMode() to draw onto a RenderTexture instead of the screen.
• Shaders: Use BeginShaderMode(shader) and EndShaderMode() to apply a Shader to subsequent drawing commands.
• Blending: Use BeginBlendMode(mode) and EndBlendMode() to change how colors are blended (e.g., additive, multiplied). EndBlendMode() resets to default alpha blending.
• Scissor Mode: Use BeginScissorMode(x, y, width, height) and EndScissorMode() to restrict drawing to a specific rectangular area of the screen.