Getting Started

Start with a small script, test it, then add one behavior at a time.

Minimal Script

gpc
main {
    // Inputs pass through unchanged.
}

main is the core loop. It runs every frame, so code here should be predictable and fast.

Read Input

Use get_val() to read the current input value.

gpc
main {
    if (get_val(BUTTON_10) > 50) {
        printf("BUTTON_10 is pressed");
    }
}

Buttons and triggers are usually 0 to 100. Sticks are usually -100 to 100.

Change Output

Use set_val() to write the output value that should be sent onward.

gpc
main {
    if (get_val(BUTTON_9) > 50) {
        set_val(BUTTON_10, 100);
    }
}

Detect One Press

Use event_active() for toggles and menu actions.

gpc
bool enabled = FALSE;

main {
    if (event_active(BUTTON_11)) {
        enabled = !enabled;
        printf("Enabled: %d", enabled);
    }
}

Use event_release() when logic should happen once after a button is released.

Add a Combo

Combos are timed actions. wait() belongs inside combo blocks.

gpc
main {
    if (event_active(BUTTON_11)) {
        combo_restart(OutputTest);
    }
}

combo OutputTest {
    set_val(BUTTON_15, 100);
    wait(100);
    set_val(BUTTON_15, 0);
}

Use Settings

Put common values at the top so users can tune them without reading the whole script.

gpc
int test_hold_ms = 100;
fix32 stick_scale = 1.20;

main {
    if (event_active(BUTTON_11)) {
        combo_restart(OutputTest);
    }

    fix32 rx = get_val(STICK_1_X) * stick_scale;
    set_val(STICK_1_X, clamp(rx, -100.0, 100.0));
}

combo OutputTest {
    set_val(BUTTON_15, 100);
    wait(test_hold_ms);
    set_val(BUTTON_15, 0);
}

Next Steps

Authoring Workflow

For new scripts, start from a minimal main block, add one behavior, compile or load the script in the host, and keep the host log panel open while testing. Use a controller monitor to compare input, script-facing value, and output. Remove noisy printf() calls once the script is stable.

When a script does not behave as expected, temporarily simplify it back to one input and one output. That makes it much easier to tell whether the issue is syntax, logic, controller mapping, or the host output path.

Common Mistakes

  • Use wait() only inside combo blocks.
  • Use event_active() for toggles instead of checking get_val() every tick.
  • Use get_actual() when you need the physical input after your script has already changed output.
  • Clamp stick or trigger math before calling set_val().
  • Keep main fast. Avoid loops that can run for a long time.
  • Keyboard and mouse functions depend on host/plugin support.

AI-Assisted Authoring Notes

When asking an AI assistant to write GPC3, include the target controller layout, the exact trigger buttons, the desired value ranges, and whether the script should use passthrough, combos, keyboard, or mouse state. Ask for a small first version before adding profiles, menus, or multiple toggles.

← PreviousOverviewNext →Syntax