Wicked Engine Documentation

Wicked Engine is a static library that you include and link into your C++ application.

Windows Setup

1. Open WickedEngine.sln in Visual Studio.
2. Build the WickedEngine_Windows project.
3. In your application's build system:
   • Add $(SolutionDir)WickedEngine to your "additional include directories".
   • Add $(SolutionDir)BUILD/$(Platform)/$(Configuration) to your "additional library directories".
   • Include #include "WickedEngine.h" in your code.

Linux Setup

1. Install dependencies:

sudo apt update
sudo apt install libsdl2-dev build-essential

2. Build using cmake and make:

mkdir build
cd build
cmake ..
make

3. Configure your application's build system to point to the resulting include and library directories as described in the Windows setup.

If you encounter issues, refer to the Samples/Template projects for correct configuration examples.

# Linux build commands
mkdir build
cd build
cmake ..
make

You can get IntelliSense (autocomplete, signatures, and type checking) in editors like VS Code (using the sumneko.lua extension) by generating Lua Language Server (LuaLS) definitions from the Wicked Engine documentation.

1. Generate the definitions

Requires Python 3. Run the following command from the documentation directory:

cd Content/Documentation/scripting_api
python3 generate_stubs.py

This creates wicked_engine_bindings.lua. To generate separate files per topic instead, use:

python3 generate_stubs.py --split

2. Install into your project

Copy the generated wicked_engine_bindings.lua into your project directory (e.g., into a library/ folder).

3. Configure .luarc.json

Create a .luarc.json file at your project root to point the language server to the definitions:

{
  "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
  "workspace": {
    "library": ["library/wicked_engine_bindings.lua"],
    "checkThirdParty": false
  },
  "runtime": {
    "version": "Lua 5.4"
  }
}

If your project uses custom globals that aren't defined in your scripts, add them to diagnostics.globals to prevent error reporting:

"diagnostics": {
  "globals": [ "my_custom_global", "MY_CONSTANT" ]
}

You can perform asynchronous workloads on the compute queue using CommandList granularity.

Usage

Pass the QUEUE_TYPE parameter to BeginCommandList(). By default, work is executed on QUEUE_GRAPHICS.

• QUEUE_GRAPHICS: The main queue; can execute both graphics and compute work.
• QUEUE_COMPUTE: Can only execute compute work.
• Fallback: If the API/device does not support async compute (e.g., DX11), QUEUE_GRAPHICS is used.

Synchronization

Use WaitCommandList(CommandList first, CommandList second) to insert a GPU dependency barrier. This makes first wait for second to finish. This is a GPU-side operation and does not block the CPU.

Note on Resource States: The SHADER_RESOURCE state cannot be used on the compute queue. You must use SHADER_RESOURCE_COMPUTE as the starting state for resources used in a compute queue, and transition them back to SHADER_RESOURCE before use in a pixel shader.

CommandList cmd0 = device->BeginCommandList(QUEUE_GRAPHICS);
CommandList cmd1 = device->BeginCommandList(QUEUE_COMPUTE);
device->WaitCommandList(cmd1, cmd0); // cmd1 waits for cmd0 to finish
CommandList cmd2 = device->BeginCommandList(QUEUE_GRAPHICS);
CommandList cmd3 = device->BeginCommandList(QUEUE_GRAPHICS);
device->WaitCommandList(cmd3, cmd1); // cmd3 waits for cmd1 to finish

device->SubmitCommandLists();

Wicked Engine uses an Entity-Component System where an Entity is a unique identifier (number) and data is stored in ComponentManager<T> containers. To bind data to an entity, you create a component within a manager associated with that entity ID.

Key Concepts:

• Entity: A unique ID. It does not require components to be valid.
• ComponentManager<T>: Manages contiguous memory for components of type T.
• Memory Safety:
  • Pointer/Index Invalidation: Adding or removing components can reallocate memory or change the order of elements (the manager is kept dense). Never store long-lived pointers or indices to components; always re-query using GetComponent(entity) or GetIndex(entity) after structural changes.
  • Array Operator: Do NOT use components[entity]. This is invalid and will cause undefined behavior or crashes. Use GetComponent(entity) instead.

Iteration Patterns:

• Linear Iteration: Use GetCount(), components[i], and components.GetEntity(i) to iterate through all components and their associated entities in order.
• Random Access: Use GetComponent(entity) to find a component for a specific entity, or GetIndex(entity) to find its current position in the contiguous array.

struct MyComponent
{
	float3 position;
	float speed;
};
ComponentManager<MyComponent> components; // create a component manager
Entity entity = CreateEntity(); // create a new entity ID
MyComponent& component = components.Create(entity); // create a component and bind it to the entity

// To query a component for a given entity:
MyComponent* component = components.GetComponent(entity);
if(component != nullptr) 
{
	// use component
}

// To get the index of an entity:
size_t index = components.GetIndex(entity);
if(index != INVALID_INDEX) 
{
	MyComponent& component = components[index];
}