> For the complete documentation index, see [llms.txt](https://guide.cronuszen.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.cronuszen.com/gpcscripting/gpc-script-guide/reference/additional-built-ins/bit-and-math-built-ins.md).

# Bit and math built-ins

These functions operate on current 32-bit GPC integers. Valid bit indexes are `0..31`. GPC integer division truncates, and arithmetic overflow must be prevented by the script.

***

#### `set_bit`

Sets one bit in a writable variable.

**Syntax**

```gpc
set_bit(variable, bit_index);
```

**Parameters**

* `variable`: a runtime variable to modify; an expression or const value is not accepted.
* `bit_index`: `0..31`, where `0` is the least-significant bit.

**Returns**

Nothing. The first argument is modified.

**Example**

{% code title="set-bit.gpc" %}

```gpc
int flags;

main {
    if(event_press(PS5_CROSS)) set_bit(flags, 3);
    set_val(TRACE_1, flags);
}
```

{% endcode %}

***

#### `clear_bit`

Clears one bit in a writable variable without changing its other bits.

**Syntax**

```gpc
clear_bit(variable, bit_index);
```

**Parameters**

* `variable`: a runtime variable to modify.
* `bit_index`: `0..31`.

**Returns**

Nothing.

**Example**

{% code title="clear-bit.gpc" %}

```gpc
int flags = 15;

main {
    if(event_press(PS5_CIRCLE)) clear_bit(flags, 2);
    set_val(TRACE_1, flags);
}
```

{% endcode %}

***

#### `test_bit`

Tests whether one bit is set.

**Syntax**

```gpc
result = test_bit(value, bit_index);
```

**Parameters**

* `value`: the integer to inspect.
* `bit_index`: `0..31`.

**Returns**

`TRUE` when the bit is set; otherwise `FALSE`.

**Example**

{% code title="test-bit.gpc" %}

```gpc
int flags = 8;
int feature_enabled;

main {
    feature_enabled = test_bit(flags, 3);
    set_val(TRACE_1, feature_enabled);
}
```

{% endcode %}

***

#### `set_bits`

Writes a masked multi-bit field into a writable variable at a starting bit index.

**Syntax**

```gpc
set_bits(variable, value, bit_index, bit_mask);
```

**Parameters**

* `variable`: the runtime variable to modify.
* `value`: the field value to insert.
* `bit_index`: starting position `0..31`.
* `bit_mask`: the low-bit mask describing the field width, such as `0x0F` for four bits.

**Returns**

Nothing.

**Example**

{% code title="set-bits.gpc" %}

```gpc
int packed;

main {
    // Store value 9 in the four-bit field beginning at bit 4.
    set_bits(packed, 9, 4, 0x0F);
    set_val(TRACE_1, packed);
}
```

{% endcode %}

Keep the mask and starting index identical when the field is later read.

***

#### `get_bits`

Extracts a masked field and shifts it down to the low bits.

**Syntax**

```gpc
result = get_bits(value, bit_index, bit_mask);
```

**Parameters**

* `value`: packed integer to inspect.
* `bit_index`: starting position `0..31`.
* `bit_mask`: low-bit mask for the field.

**Returns**

The extracted field value.

**Example**

{% code title="get-bits.gpc" %}

```gpc
int packed = 0x90;
int field;

main {
    field = get_bits(packed, 4, 0x0F);
    set_val(TRACE_1, field); // 9
}
```

{% endcode %}

***

#### `abs`

Returns the magnitude of a signed value.

**Syntax**

```gpc
result = abs(expression);
```

**Parameters**

* `expression`: any current-target integer expression.

**Returns**

The non-negative magnitude. Avoid the `INT32_MIN` edge because its positive magnitude is outside the signed 32-bit range.

**Example**

{% code title="abs.gpc" %}

```gpc
int stick_distance;

main {
    stick_distance = abs(get_ival(PS5_RX));
    if(stick_distance > 70) set_val(TRACE_1, 1);
}
```

{% endcode %}

***

#### `inv`

Negates a value. This is equivalent to multiplying by `-1`.

**Syntax**

```gpc
result = inv(expression);
```

**Parameters**

* `expression`: integer expression to negate.

**Returns**

The sign-inverted value.

**Example**

{% code title="inv.gpc" %}

```gpc
main {
    set_val(PS5_RY, inv(get_ival(PS5_RY)));
}
```

{% endcode %}

***

#### `pow`

Raises a base integer to an integer exponent.

**Syntax**

```gpc
result = pow(base, exponent);
```

**Parameters**

* `base`: integer base.
* `exponent`: integer exponent accepted by the target function.

**Returns**

The integer power result.

**Example**

{% code title="pow\.gpc" %}

```gpc
int cubed;

init {
    cubed = pow(5, 3); // 125
}
```

{% endcode %}

Powers grow quickly. Prove the result remains inside the signed 32-bit range before using runtime-controlled inputs.

***

#### `isqrt`

Calculates an integer square root and discards any fractional part.

**Syntax**

```gpc
result = isqrt(value);
```

**Parameters**

* `value`: non-negative integer whose square root is required.

**Returns**

The truncated integer square root.

**Example**

{% code title="isqrt.gpc" %}

```gpc
int root;

init {
    root = isqrt(10); // 3
}
```

{% endcode %}

Validate or clamp runtime input so a negative value is never passed.

***

#### `random`

Returns a pseudo-random integer between the supplied bounds.

**Syntax**

```gpc
result = random(minimum, maximum);
```

**Parameters**

* `minimum`: lower signed 32-bit bound.
* `maximum`: upper signed 32-bit bound.

**Returns**

A pseudo-random integer in the requested range.

**Example**

{% code title="random.gpc" %}

```gpc
int delay_ms;

main {
    if(event_press(PS5_CROSS)) delay_ms = random(40, 80);
    set_val(TRACE_1, delay_ms);
}
```

{% endcode %}

Keep `minimum <= maximum` and do not use this as a security or authorization mechanism.

***

#### `clamp`

Restricts a value to an inclusive lower and upper bound.

**Syntax**

```gpc
result = clamp(value, low, high);
```

**Parameters**

* `value`: value to restrict.
* `low`: minimum permitted result.
* `high`: maximum permitted result.

**Returns**

`low` when the value is too small, `high` when it is too large, or the original value when already in range.

**Example**

{% code title="clamp.gpc" %}

```gpc
int output_x;

main {
    output_x = clamp(get_ival(PS5_RX) * 2, -100, 100);
    set_val(PS5_RX, output_x);
}
```

{% endcode %}

***

#### `min`

Returns the smaller of two integers.

**Syntax**

```gpc
result = min(value1, value2);
```

**Parameters**

* `value1`: first integer.
* `value2`: second integer.

**Returns**

The smaller value.

**Example**

{% code title="min.gpc" %}

```gpc
int limited_trigger;

main {
    limited_trigger = min(get_ival(PS5_R2), 50);
    set_val(TRACE_1, limited_trigger);
}
```

{% endcode %}

***

#### `max`

Returns the larger of two integers.

**Syntax**

```gpc
result = max(value1, value2);
```

**Parameters**

* `value1`: first integer.
* `value2`: second integer.

**Returns**

The larger value.

**Example**

{% code title="max.gpc" %}

```gpc
int trigger_floor;

main {
    trigger_floor = max(get_ival(PS5_R2), 25);
    set_val(TRACE_1, trigger_floor);
}
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://guide.cronuszen.com/gpcscripting/gpc-script-guide/reference/additional-built-ins/bit-and-math-built-ins.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.