> ## Documentation Index
> Fetch the complete documentation index at: https://lua.starline.one/llms.txt
> Use this file to discover all available pages before exploring further.

# Engine

> Use combat, game-state, command, prediction, and network helpers.

Combat and game-state helpers.

```lua theme={"dark"}
events.On("createmove", function(cmd)
    local eye = engine.GetLocalEyePos()

    entity.players:ForEach(function(pawn)
        if not entity.IsAlive(pawn) or not entity.IsEnemy(pawn) then return end

        local pos = engine.GetHitboxPosition(pawn, engine.HITBOX_HEAD)
        if not pos then return end

        local dmg = engine.GetDamage(pawn, engine.HITBOX_HEAD)
        if dmg <= 0 then return end

        local ang = math.CalcAngle(eye, pos)
        local punch = engine.GetAimPunch()
        cmd.viewangles = {
            pitch = ang.pitch - (punch and punch.pitch or 0),
            yaw   = ang.yaw   - (punch and punch.yaw   or 0),
            roll  = 0
        }
        cmd.buttons = bit.bor(cmd.buttons, events.IN_ATTACK)
    end)
end)
```

## Hitboxes

### GetHitboxPosition

```lua theme={"dark"}
local pos = engine.GetHitboxPosition(pawn, hitbox_id)
```

Returns the world-space center `Vector` of a hitbox, or `nil` for a non-player entity or one with no valid skeleton. `hitbox_id` is a [hitbox constant](#hitbox-constants) or a raw index 0 to 18.

### GetHitboxData

```lua theme={"dark"}
local data = engine.GetHitboxData(pawn, hitbox_id)
if data then
    print(data.center, data.hitgroup, data.radius)
end
```

Same arguments as `GetHitboxPosition`, but returns the whole shape.

| Field      | Type     |                                                       |
| ---------- | -------- | ----------------------------------------------------- |
| `center`   | `Vector` | world-space center                                    |
| `mins`     | `Vector` | world-space transformed min bounds                    |
| `maxs`     | `Vector` | world-space transformed max bounds                    |
| `hitgroup` | number   | hitgroup index (1 = head, 2 = chest, ...)             |
| `radius`   | number   | shape radius for sphere/capsule hitboxes, -1 for hull |

## Visibility

Build it from [Trace](/trace): `trace.Shape` from `GetLocalEyePos()` to `GetHitboxPosition()`, plus `trace.Smoke` if you care about smokes. Loop hitboxes yourself for multipoint.

```lua theme={"dark"}
local function visible(pawn, hitbox)
    local eye, pos = engine.GetLocalEyePos(), engine.GetHitboxPosition(pawn, hitbox)
    if not pos or trace.Smoke(eye, pos) then return false end
    local tr = trace.Shape(eye, pos, { ignore = entity.GetLocalPlayer() })
    return not tr.hit or tr.entity == pawn
end
```

## Damage

### GetDamage

```lua theme={"dark"}
local dmg = engine.GetDamage(target_pawn, hitbox_id)
```

Returns estimated integer damage after penetration, range falloff, hitgroup scaling, and armor. Returns `0` when the shot cannot be simulated or hit the target.

### FireBullet

```lua theme={"dark"}
local result = engine.FireBullet(start_vec, end_vec [, target_pawn])
```

Simulates a shot from `start` to `end`. `target_pawn` limits the target when provided. Returns `nil` if the local player or weapon data is unavailable.

| Field        | Type     |                               |
| ------------ | -------- | ----------------------------- |
| `hit`        | boolean  | bullet reached a target       |
| `damage`     | number   | post-scaling damage (integer) |
| `hitbox`     | number   | hitbox index                  |
| `penetrated` | boolean  | shot passed through a surface |
| `position`   | `Vector` | final impact position         |
| `entity`     | entity   | entity that was hit, or `nil` |

## Weapon

Read weapon state from `pawn.m_pWeaponServices.m_hActiveWeapon`. Read weapon stats with [`entity.GetWeaponData`](/entity#getweapondata).

### CanShoot

```lua theme={"dark"}
if engine.CanShoot() then ... end
```

Returns `true` if the local player can fire right now: holding a gun, has ammo, not reloading, attack cooldown elapsed.

## Spread

### GetInaccuracy

```lua theme={"dark"}
local inacc = engine.GetInaccuracy()
```

Predicted weapon inaccuracy for the current tick, or `nil` if prediction hasn't run. This is the value the server will evaluate, sampled mid-prediction (not the stale post-restore value).

### GetSpread

```lua theme={"dark"}
local spread = engine.GetSpread()
```

Predicted weapon base spread, or `nil`.

## Recoil

### GetAimPunch

```lua theme={"dark"}
local punch = engine.GetAimPunch()
if punch then
    cmd.viewangles.pitch = cmd.viewangles.pitch - punch.pitch
    cmd.viewangles.yaw   = cmd.viewangles.yaw   - punch.yaw
end
```

Returns the current aim punch as a `QAngle`, or `nil` when no local player is available.

## Local state

Values you can't read off the pawn directly. Everything else (origin, velocity, tickbase) is a plain schema field, read off `entity.GetLocalPlayer()`.

These track the controlled player and freeze while you're spectating. For observer-camera visuals use `entity.GetLocalPlayerOrSpec()` instead.

### GetLocalEyePos

```lua theme={"dark"}
local eye = engine.GetLocalEyePos()
```

### GetLocalViewAngles

```lua theme={"dark"}
local angles = engine.GetLocalViewAngles()
```

The view angles the cheat's own features solve against, sampled once per command.

### GetViewAngles / SetViewAngles

```lua theme={"dark"}
local ang = engine.GetViewAngles()
engine.SetViewAngles(QAngle(0, 90, 0))
```

Gets or sets the live camera angles. Both `SetViewAngles` and changes to `cmd.viewangles` visibly move the camera.

## Console

### ExecuteCommand

```lua theme={"dark"}
engine.ExecuteCommand("say hello")
engine.ExecuteCommand("disconnect")
```

Executes a console command. `+` and `-` input-bind commands are rejected; use the button API instead. Calls made off the game thread are queued.

## Player name

### SetName

```lua theme={"dark"}
local ok = engine.SetName("new name")
```

Changes the local player name. Returns whether it succeeded. Passing `nil` restores the real name.

### ResetName

```lua theme={"dark"}
local ok = engine.ResetName()
```

Restores the local player's real name. Returns whether it succeeded.

## Subticks

### ClearSubtickMovement

```lua theme={"dark"}
events.On("createmove", function(cmd)
    engine.ClearSubtickMovement()
    cmd.forwardmove = 1
end)

engine.ClearSubtickMovement(true)   -- drop the angle deltas as well
```

Drops movement deltas from the current command's subtick steps. Steps containing only movement are removed; button and angle steps are kept. Pass `true` to remove angle deltas too. Available only in `movement` and `createmove`.

<Warning>
  Writing `cmd.buttons` afterwards puts steps back: the diff goes through the engine's button path, which emits a subtick step per changed bit.
</Warning>

### GetSubticks

```lua theme={"dark"}
for _, step in ipairs(engine.GetSubticks()) do
    print(step.when, step.yaw_delta)
end
```

Returns the current command's subtick steps in order. Available only in `movement` and `createmove`.

| Field           | Type    |                                                   |
| --------------- | ------- | ------------------------------------------------- |
| `when`          | number  | `0..1` through the tick                           |
| `button`        | number  | button bit, `0` for a step that carries no button |
| `pressed`       | boolean | press or release                                  |
| `forward_delta` | number  | movement delta against the last command move      |
| `left_delta`    | number  | same, sideways                                    |
| `pitch_delta`   | number  | view angle delta                                  |
| `yaw_delta`     | number  | view angle delta                                  |

### AddSubtick

```lua theme={"dark"}
engine.AddSubtick({ when = 0.5, yaw_delta = 12.0 })
```

Appends a step to the current command. Available only in `movement` and `createmove`. Returns `false` at the step limit.

Fields are optional: `when`, `button`, `pressed`, `forward_delta`, `left_delta`, `pitch_delta`, and `yaw_delta`. Unset fields default to `0` or `false`.

Movement values are deltas from the movement service's last command. For example:

```lua theme={"dark"}
local ms = entity.GetLocalPlayer().m_pMovementServices
engine.AddSubtick({
    forward_delta = cmd.forwardmove - ms.m_flCmdForwardMove,
    left_delta    = cmd.leftmove - ms.m_flCmdLeftMove,
})
```

## Buttons

### AddButton / RemoveButton

```lua theme={"dark"}
engine.AddButton(events.IN_DUCK, false)
engine.RemoveButton(events.IN_FORWARD, true, 0.25)
```

Press or release a button directly. `movement` and `createmove` only.

| Arg            | Default |                                                                        |
| -------------- | ------- | ---------------------------------------------------------------------- |
| `button`       |         | bit, or a mask; a mask is split into one step per bit                  |
| `subtick`      | `false` | also emit a subtick step for the edge                                  |
| `when`         | `0`     | fraction through the tick; `0` resolves to the predicted tick fraction |
| `only_subtick` | `false` | `RemoveButton` only: leave the raw bit alone                           |

These functions change the command directly. Set `subtick` to emit a timed subtick edge.

## Prediction

### GetMaxSpeed

```lua theme={"dark"}
local speed = engine.GetMaxSpeed()
```

Predicted max movement speed from the last prediction run.

### GetPostState

```lua theme={"dark"}
local post = engine.GetPostState()
if post and not post.on_ground then ... end
```

The local player's state after the prediction run for this command, which is where the player ends the tick and what the server evaluates. `nil` when prediction hasn't run.

| Field                            | Type     |                          |
| -------------------------------- | -------- | ------------------------ |
| `origin`                         | `Vector` | absolute origin          |
| `velocity`                       | `Vector` | networked velocity       |
| `abs_velocity`                   | `Vector` |                          |
| `base_velocity`                  | `Vector` | conveyor / push velocity |
| `view_offset`                    | `Vector` |                          |
| `flags`                          | number   | `m_fFlags`               |
| `on_ground`                      | boolean  | `flags & FL_ONGROUND`    |
| `move_type` / `actual_move_type` | number   |                          |
| `tickbase`                       | number   |                          |
| `water_level`                    | number   |                          |
| `velocity_modifier`              | number   |                          |
| `fall_velocity`                  | number   |                          |
| `accuracy_penalty`               | number   |                          |
| `in_landing`                     | boolean  |                          |
| `is_walking`                     | boolean  |                          |

## Network

### GetPing

```lua theme={"dark"}
local ms = engine.GetPing()
```

Network latency in milliseconds. Every other time value in the API is in seconds.

### GetServerTick

```lua theme={"dark"}
local tick = engine.GetServerTick()
```

### GetClientTick

```lua theme={"dark"}
local tick = engine.GetClientTick()
```

### GetServerAddress

```lua theme={"dark"}
local addr = engine.GetServerAddress()
```

Server IP/hostname string, or `nil`.

### GetTimeConnected

```lua theme={"dark"}
local seconds = engine.GetTimeConnected()
```

## Hitbox constants

| Constant                | Value |
| ----------------------- | ----- |
| `engine.HITBOX_HEAD`    | 0     |
| `engine.HITBOX_NECK`    | 1     |
| `engine.HITBOX_PELVIS`  | 2     |
| `engine.HITBOX_STOMACH` | 3     |
| `engine.HITBOX_CHEST`   | 5     |

Only the common aim targets are bound. Valid indices run `0` to `18`; pass the raw number for limb hitboxes.