> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: utils
description: Memory access, traces, and random utilities
icon: wrench
---

The `utils` namespace provides console execution, traces, memory access, and random helpers.

## console\_exec

```lua
utils.console_exec(cmd: string[, ...])
```

> Executes a console command. Multiple commands can be combined with ';'. Be careful when passing user input (including usernames) to it.

<Schema title="Parameters">
  <SchemaField name="cmd" type="string" required>
    The console command(s) to execute.
  </SchemaField>

  <SchemaField name="..." type="any">
    Comma-separated arguments to concatenate with cmd.
  </SchemaField>
</Schema>

## execute\_after

```lua
utils.execute_after(delay: number, callback: function[, ...])
```

> Executes the callback after delay seconds, passing the arguments to it.

<Schema title="Parameters">
  <SchemaField name="delay" type="number" required>
    Time in seconds to wait before calling callback.
  </SchemaField>

  <SchemaField name="callback" type="function" required>
    The Lua function that will be called after the delay.
  </SchemaField>

  <SchemaField name="..." type="any">
    Arguments that will be passed to the callback.
  </SchemaField>
</Schema>

## net\_channel

```lua
utils.net_channel(): NetChannel
```

> Returns the `NetChannel` struct.

<Schema title="Returns">
  <SchemaField name="channel" type="NetChannel">
    The `NetChannel` struct.
  </SchemaField>
</Schema>

## trace\_line

```lua
utils.trace_line(from: vector, to: vector[, skip: entity/table/function, mask: number, type: number]): trace
```

> Returns a `trace` struct containing all the information. See the [UTIL\_TraceLine](https://developer.valvesoftware.com/wiki/UTIL_TraceLine) reference for more details.

<Schema title="Parameters">
  <SchemaField name="from" type="vector" required>
    Vector to start tracing from.
  </SchemaField>

  <SchemaField name="to" type="vector" required>
    Vector to trace to.
  </SchemaField>

  <SchemaField name="skip" type="entity, table, function">
    Optional. Entity skipping options.
  </SchemaField>

  <SchemaField name="mask" type="number">
    Optional. Trace mask.
  </SchemaField>

  <SchemaField name="type" type="number">
    Optional. Trace type \[0-3]. 0: Trace everything \[Default]. 1: Trace world only. 2: Trace entities only. 3: Trace everything filter props.
  </SchemaField>
</Schema>

<Note>
  The `skip` argument can either be an `entity` object, a table with `entity` objects, or a function, like the ShouldHitEntity callback. If you use it as a callback, you can access the `entity` and `contents_mask` by adding them to the function arguments. Inside the callback, return true if tracing should not skip the entity, otherwise return false.
</Note>

<Schema title="Returns">
  <SchemaField name="trace" type="trace">
    A `trace` struct containing all the information.
  </SchemaField>
</Schema>

## trace\_hull

```lua
utils.trace_hull(from: vector, to: vector, mins: vector, maxs: vector[, skip: entity/table/function, mask: number, type: number]): trace
```

> Returns a `trace` struct containing all the information.

<Schema title="Parameters">
  <SchemaField name="from" type="vector" required>
    Vector to start tracing from.
  </SchemaField>

  <SchemaField name="to" type="vector" required>
    Vector to trace to.
  </SchemaField>

  <SchemaField name="mins" type="vector" required>
    Hull mins.
  </SchemaField>

  <SchemaField name="maxs" type="vector" required>
    Hull maxs.
  </SchemaField>

  <SchemaField name="skip" type="entity, table, function">
    Optional. Entity skipping options.
  </SchemaField>

  <SchemaField name="mask" type="number">
    Optional. Trace mask.
  </SchemaField>

  <SchemaField name="type" type="number">
    Optional. Trace type \[0-3]. 0: Trace everything \[Default]. 1: Trace world only. 2: Trace entities only. 3: Trace everything filter props.
  </SchemaField>
</Schema>

<Note>
  The `skip` argument can either be an `entity` object, a table with `entity` objects, or a function, like the ShouldHitEntity callback. If you use it as a callback, you can access the `entity` and `contents_mask` by adding them to the function arguments. Inside the callback, return true if tracing should not skip the entity, otherwise return false.
</Note>

<Schema title="Returns">
  <SchemaField name="trace" type="trace">
    A `trace` struct containing all the information.
  </SchemaField>
</Schema>

## trace\_bullet

```lua
utils.trace_bullet(from_entity: entity, from: vector, to: vector[, skip: entity/table/function]): number, trace
```

> Returns the `damage`, `trace` arguments.

<Schema title="Parameters">
  <SchemaField name="from_entity" type="entity" required>
    Player whose weapon will be used for this trace.
  </SchemaField>

  <SchemaField name="from" type="vector" required>
    Vector to start tracing from.
  </SchemaField>

  <SchemaField name="to" type="vector" required>
    Vector to trace to.
  </SchemaField>

  <SchemaField name="skip" type="entity, table, function">
    Optional. Entity skipping options. If not passed, the skip entity will be from\_entity.
  </SchemaField>
</Schema>

<Note>
  The `skip` argument can either be an `entity` object, a table with `entity` objects, or a function, like the ShouldHitEntity callback. If you use it as a callback, you can access the `entity` and `contents_mask` by adding them to the function arguments. Inside the callback, return true if tracing should not skip the entity, otherwise return false.
</Note>

<Schema title="Returns">
  <SchemaField name="damage" type="number">
    The damage value.
  </SchemaField>

  <SchemaField name="trace" type="trace">
    A `trace` struct containing all the information.
  </SchemaField>
</Schema>

<AccordionGroup>
  <Accordion title="struct trace">
    <Schema>
      <SchemaField name="start_pos" type="vector">
        Start position.
      </SchemaField>

      <SchemaField name="end_pos" type="vector">
        Final position.
      </SchemaField>

      <SchemaField name="plane" type="table">
        Surface normal at impact. Contains normal, dist, type, and signbits values.
      </SchemaField>

      <SchemaField name="fraction" type="number">
        Percentage in the range \[0.0, 1.0]. How far the trace went before hitting something. 1.0 - didn't hit anything.
      </SchemaField>

      <SchemaField name="contents" type="number">
        Contents on other side of surface hit.
      </SchemaField>

      <SchemaField name="disp_flags" type="number">
        Displacement flags for marking surfaces with data.
      </SchemaField>

      <SchemaField name="all_solid" type="boolean">
        Returns true if the plane is invalid.
      </SchemaField>

      <SchemaField name="start_solid" type="boolean">
        Returns true if the initial point was in a solid area.
      </SchemaField>

      <SchemaField name="fraction_left_solid" type="number">
        Percentage in the range \[0.0, 1.0]. How far the trace went before leaving solid. Only valid if we started in solid.
      </SchemaField>

      <SchemaField name="surface" type="table">
        Surface hit (impact surface). Contains name, props, and flags values.
      </SchemaField>

      <SchemaField name="hitgroup" type="number">
        0 - generic, non-zero is specific body part.
      </SchemaField>

      <SchemaField name="physics_bone" type="number">
        Physics bone that was hit by the trace.
      </SchemaField>

      <SchemaField name="world_surface_index" type="number">
        Index of the msurface2\_t, if applicable.
      </SchemaField>

      <SchemaField name="entity" type="entity">
        Entity that was hit by the trace.
      </SchemaField>

      <SchemaField name="hitbox" type="number">
        Box that was hit by the trace.
      </SchemaField>

      <SchemaField name="did_hit" type="function">
        Returns true if there was any kind of impact at all.
      </SchemaField>

      <SchemaField name="did_hit_world" type="function">
        Returns true if the entity points at the world entity.
      </SchemaField>

      <SchemaField name="did_hit_non_world" type="function">
        Returns true if the trace hit something and it wasn't the world.
      </SchemaField>

      <SchemaField name="is_visible" type="function">
        Returns true if the final position is visible.
      </SchemaField>
    </Schema>
  </Accordion>
</AccordionGroup>

## opcode\_scan

```lua
utils.opcode_scan(module: string, signature: string[, offset: number]): userdata
```

> Returns a pointer to the specified pattern if it was found. Otherwise returns `nil`.

<Schema title="Parameters">
  <SchemaField name="module" type="string" required>
    Module name, in which the signature will be scanned.
  </SchemaField>

  <SchemaField name="signature" type="string" required>
    IDA style signature, the wildcard is "?".
  </SchemaField>

  <SchemaField name="offset" type="number">
    Optional offset to apply to the pointer address.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="pointer" type="userdata">
    A pointer to the specified pattern if it was found. Otherwise `nil`.
  </SchemaField>
</Schema>

## create\_interface

```lua
utils.create_interface(module: string, interface: string): userdata
```

> Returns a pointer to the specified interface if it was found. Otherwise returns `nil`.

<Schema title="Parameters">
  <SchemaField name="module" type="string" required>
    Module name containing the interface.
  </SchemaField>

  <SchemaField name="interface" type="string" required>
    Interface name.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="pointer" type="userdata">
    A pointer to the specified interface if it was found. Otherwise `nil`.
  </SchemaField>
</Schema>

## get\_netvar\_offset

```lua
utils.get_netvar_offset(table: string, prop: string): number
```

> Returns the offset of the specified prop. Can be used to manually navigate to the net prop.

<Schema title="Parameters">
  <SchemaField name="table" type="string" required>
    Datatable name.
  </SchemaField>

  <SchemaField name="prop" type="string" required>
    Prop name.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="offset" type="number">
    The offset of the specified prop.
  </SchemaField>
</Schema>

## get\_vfunc

> Creates and returns a wrapper function that calls a virtual table function on the specified index.

<Tabs>
  <Tab title="By index">
    ```lua
    utils.get_vfunc(index: number, ...): function
    ```

    Creates and returns a wrapper function that calls a virtual table function on the specified index.

    <Schema title="Parameters">
      <SchemaField name="index" type="number" required>
        Virtual table index of the function.
      </SchemaField>

      <SchemaField name="..." type="any">
        FFI C Type definition.
      </SchemaField>
    </Schema>

    <Schema title="Returns">
      <SchemaField name="wrapper" type="function">
        A wrapper function that calls the virtual table function.
      </SchemaField>
    </Schema>
  </Tab>

  <Tab title="By interface">
    ```lua
    utils.get_vfunc(module: string, interface: string, index: number, ...): function
    ```

    Creates and returns a wrapper function that calls a virtual table function from the specified interface on the specified index.

    <Schema title="Parameters">
      <SchemaField name="module" type="string" required>
        Module name containing the interface.
      </SchemaField>

      <SchemaField name="interface" type="string" required>
        Interface name.
      </SchemaField>

      <SchemaField name="index" type="number" required>
        Virtual table index of the function.
      </SchemaField>

      <SchemaField name="..." type="any">
        FFI C Type definition.
      </SchemaField>
    </Schema>

    <Schema title="Returns">
      <SchemaField name="wrapper" type="function">
        A wrapper function that calls the virtual table function.
      </SchemaField>
    </Schema>
  </Tab>
</Tabs>

## random\_int

```lua
utils.random_int(min: number, max: number): number
```

> Returns a random integer value.

<Schema title="Parameters">
  <SchemaField name="min" type="number" required>
    Minimum boundary for the random value, included.
  </SchemaField>

  <SchemaField name="max" type="number" required>
    Maximum boundary for the random value, included.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    A random integer value.
  </SchemaField>
</Schema>

## random\_float

```lua
utils.random_float(min: number, max: number): number
```

> Returns a random float value.

<Schema title="Parameters">
  <SchemaField name="min" type="number" required>
    Minimum boundary for the random value, included.
  </SchemaField>

  <SchemaField name="max" type="number" required>
    Maximum boundary for the random value, included.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="value" type="number">
    A random float value.
  </SchemaField>
</Schema>

## random\_seed

```lua
utils.random_seed(seed: number)
```

> Sets the new random seed.

<Schema title="Parameters">
  <SchemaField name="seed" type="number" required>
    New random seed value.
  </SchemaField>
</Schema>

## `NetChannel`

<Note>
  Access the struct via [`.net_channel`](/csgo/api-reference/namespaces/utils#net_channel) function.

  * `FLOW:OUTGOING = 0`
  * `FLOW:INCOMING = 1`
</Note>

## time

```lua
net.time: number
```

> Current network time.

## time\_connected

```lua
net.time_connected: number
```

> Connection time in seconds.

## time\_since\_last\_received

```lua
net.time_since_last_received: number
```

> Time since last received packet in seconds.

## is\_loopback

```lua
net.is_loopback: boolean
```

> Returns `true` if server is a loopback (local server).

## is\_playback

```lua
net.is_playback: boolean
```

> Returns `true` if demo is being played.

## is\_timing\_out

```lua
net.is_timing_out: boolean
```

> Returns `true` if client is timing out.

## sequence\_nr\[`flow`]

```lua
net.sequence_nr[0]: number
net.sequence_nr[1]: number
```

> Last sent sequence number.

## latency\[`flow`]

```lua
net.latency[0]: number
net.latency[1]: number
```

> Current latency (RTT), more accurate but jittering.

## avg\_latency\[`flow`]

```lua
net.avg_latency[0]: number
net.avg_latency[1]: number
```

> Average latency in seconds.

## loss\[`flow`]

```lua
net.loss[0]: number
net.loss[1]: number
```

> Percentage in the range \[0.0, 1.0] of the current packet loss.

## choke\[`flow`]

```lua
net.choke[0]: number
net.choke[1]: number
```

> Percentage in the range \[0.0, 1.0] of the current packet choke.

## packets\[`flow`]

```lua
net.packets[0]: number
net.packets[1]: number
```

> Average amount of packets/sec.

## data\[`flow`]

```lua
net.data[0]: number
net.data[1]: number
```

> Data flow in bytes/sec.

## total\_packets\[`flow`]

```lua
net.total_packets[0]: number
net.total_packets[1]: number
```

> Total amount of packets/sec.

## total\_data\[`flow`]

```lua
net.total_data[0]: number
net.total_data[1]: number
```

> Total data flow in bytes/sec.

## get\_server\_info

```lua
net:get_server_info(): table
```

> Returns a table containing `rate`, `name`, `address`, `frame_time`, and `deviation` (or `nil` on failure).

<Schema title="Returns">
  <SchemaField name="info" type="table">
    A table containing `rate`, `name`, `address`, `frame_time`, and `deviation` (or `nil` on failure).
  </SchemaField>
</Schema>

## is\_valid\_packet

```lua
net:is_valid_packet(flow: number, frame: number): number
```

> Returns `true` if the packet is valid.

<Schema title="Parameters">
  <SchemaField name="flow" type="number" required>
    Channel (Flow).
  </SchemaField>

  <SchemaField name="frame" type="number" required>
    Sequence number.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="valid" type="number">
    `true` if the packet is valid.
  </SchemaField>
</Schema>

## get\_packet\_time

```lua
net:get_packet_time(flow: number, frame: number): number
```

> Returns the time when the packet was sent.

<Schema title="Parameters">
  <SchemaField name="flow" type="number" required>
    Channel (Flow).
  </SchemaField>

  <SchemaField name="frame" type="number" required>
    Sequence number.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="time" type="number">
    The time when the packet was sent.
  </SchemaField>
</Schema>

## get\_packet\_bytes

```lua
net:get_packet_bytes(flow: number, frame: number, group: number): number
```

> Returns the group size of this packet.

<Schema title="Parameters">
  <SchemaField name="flow" type="number" required>
    Channel (Flow).
  </SchemaField>

  <SchemaField name="frame" type="number" required>
    Sequence number.
  </SchemaField>

  <SchemaField name="group" type="number" required>
    Group of this packet.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="bytes" type="number">
    The group size of this packet.
  </SchemaField>
</Schema>

## get\_packet\_response\_latency

```lua
net:get_packet_response_latency(flow: number, frame: number): number, number
```

> Returns `latency_msecs`, `choke` of this packet.

<Schema title="Parameters">
  <SchemaField name="flow" type="number" required>
    Channel (Flow).
  </SchemaField>

  <SchemaField name="frame" type="number" required>
    Sequence number.
  </SchemaField>
</Schema>

<Schema title="Returns">
  <SchemaField name="latency_msecs" type="number">
    The response latency of this packet in milliseconds.
  </SchemaField>

  <SchemaField name="choke" type="number">
    The choke of this packet.
  </SchemaField>
</Schema>
