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

---
title: Reading API Pages
icon: book-open
sidebar_position: 4
---

# Reading API Pages

API Reference pages are written for the script you are about to write. Each
page lists its symbols (a global table, an object type, an enum) as sections, and
every function, method, field or operator of a symbol as a card. Scan the card
heads for the name you need, then open a card for its signature, arguments,
return values and examples.

<Note>
  This page describes the generated pages as they appear in the browser. Treat
  the signature block as a readable call guide, not as Lua code that should be
  copied into your script.
</Note>

## Member cards

A card's head shows a kind badge, the member name with its argument names, and
the first sentence of its description. Click the head to open the card; only one
card per group is open at a time. The link icon copies a link to that card, and
the table of contents lists every card on the page.

| Badge                          | What it is                 | How you use it                 |
| ------------------------------ | -------------------------- | ------------------------------ |
| <ApiKindBadge kind="fn" />     | function of a global table | `entity.GetLocalPawn()`        |
| <ApiKindBadge kind="method" /> | method of an object        | `pawn:IsValid()`               |
| <ApiKindBadge kind="prop" />   | field or property          | `globals.curtime`              |
| <ApiKindBadge kind="meta" />   | operator or metamethod     | `a + b`, `#v`                  |
| <ApiKindBadge kind="ctor" />   | calling the type itself    | `Vector(1, 2, 3)`              |
| <ApiKindBadge kind="type" />   | type alias                 | `entity.PawnObserveePredicate` |
| <ApiKindBadge kind="event" />  | event callback             | `events.render(fn)`            |

An open card shows, in order: the signature line, longer notes, **Applies to**
(the object classes a method accepts), **Parameters**, **Returns** (when results
are named or described), examples, and a footer with tags such as `nodiscard`
and an **Edit** link to the source file.

## Signature line

The signature line inside a card has the callable name, argument names and
types, optional badges, and returned values after the return arrow.

Use that line to answer practical questions:

* what name you call;
* whether you call it with dot syntax (`entity.ListByClassName`) or colon syntax (`pawn:IsValid`);
* which arguments exist and which ones are optional;
* whether the return is a normal value, a nullable value, or an iterator triple;
* which type page you can click next.

For example, [`entity.IteratePlayers`](/cs2/api_reference/engine/entity#entity-IteratePlayers)
shows optional filters and returns values shaped for a Lua generic `for` loop.
That is why the usual script reads controller/pawn pairs like this:

```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/introduction/reading-these-docs:0:7d42e33eea51"
for controller, pawn in entity.IteratePlayers(true, false) do
    print(controller:GetPlayerName(), ": ", pawn:GetHealth(), " hp")
end
```

## Section labels

The quiet label next to a section heading tells you what that symbol is. A
`global table` groups functions; an `object type` describes values the API
returns; a `ctype` is a C type object you can call as a constructor; a `cdata`
section describes the C values created by or returned from the API. `callable`
means the symbol itself can be called. The chips under the description count
the section's members and jump to their group.
For example, `projection.Rect` is a ctype and `projection.Rect()` returns a
`ProjectionRect` cdata value.

See the FFI crash course for an
[explanation of ctype and cdata](/cs2/api_reference/tutorials/ffi-crash-course#ctype-and-cdata).
The labels do not tell you whether storage is owned or borrowed; check the API's lifetime notes.

## Signature tokens

The renderer uses short tokens so the line stays readable even for overloaded
or generic functions:

<Columns cols={2}>
  <Card title="OPT" icon="badge">
    The argument is optional. You may omit it, or pass `nil` when you need to skip to a later optional slot.
  </Card>

  <Card title="Return arrow" icon="arrow-right">
    Values after the arrow are returned by the call. If several values are listed, Lua receives all of them.
  </Card>

  <Card title="or" icon="git-branch">
    A union. `boolean or number or nil` means any one of those values may be returned.
  </Card>

  <Card title="nil" icon="circle-slash">
    A nullable result. Always check it before calling methods on the value.
  </Card>

  <Card title="Clickable types" icon="mouse-pointer-click">
    Colored type names link to API type pages or Dumped Data schema pages when a target exists.
  </Card>

  <Card title="Quoted values" icon="quote">
    A quoted chip, such as `"#"`, is a literal value accepted by that argument.
  </Card>

  <Card title="T and V" icon="braces">
    Generic placeholders. The concrete type depends on the value you passed in or the container you are reading.
  </Card>

  <Card title="T[]" icon="list">
    An array-like Lua table of `T` values. A schema collection's `:Value()` returns a one-based table snapshot.
  </Card>

  <Card title="..." icon="ellipsis">
    Varargs. The call accepts additional values after the listed arguments.
  </Card>

  <Card title="ffi.ct*" icon="binary">
    A C type specification: a declaration string, a ctype object, or a cdata value used as a type template.
  </Card>
</Columns>

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/api_reference/introduction/reading-these-docs:1:c5a4260678be"
local bomb = entity.FirstByClassName("C_PlantedC4")
if bomb then
    print(bomb:GetAbsOrigin())
end
```

Nullable results are common for lookup-style functions. The docs show that as
`or nil`, and your script should branch before using the returned object.

## Multiple returns

Some signatures return more than one value. The values are shown comma by
comma after the return arrow.

[`time.GetLocalTime`](/cs2/api_reference/runtime/time#time-GetLocalTime)
returns four values: hour, minute, second, and millisecond.

```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/introduction/reading-these-docs:2:d49349ff11e5"
local hour, minute, second, millisecond = time.GetLocalTime()
print(string.format("%02d:%02d:%02d.%03d", hour, minute, second, millisecond))
```

Iterator-style functions also return several values, but you usually do not
store them manually. Lua consumes the iterator, state, and first control value
for you in a generic `for` loop. That is what signatures like `ipairs(...)` and
`entity.IteratePlayers(...)` are showing.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/api_reference/introduction/reading-these-docs:3:0b9954dcea4a"
for index, value in ipairs({ "ak47", "awp" }) do
    print(index, ": ", value)
end
```

When the first returned value is shown as a function-shaped chip, it means the
returned value itself is callable. This usually appears on iterator helpers,
where Lua calls the iterator function internally on each loop step.

## Generic arrays and schema vectors

`T[]` means "an array-like table of the same kind of value represented by `T`."
You will see it on generated schema helpers such as `value.AtomicCollection:Value()`.

```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/introduction/reading-these-docs:4:7e0e523047e7"
local pawn = entity.GetLocalPlayerPawn()

if pawn and pawn:IsValid() then
    local weapons = pawn:GetMyWeapons()

    if weapons then
        for _, weapon in ipairs(weapons:Value()) do
            if weapon and weapon:IsValid() then
                print(weapon:GetClassName())
            end
        end
    end
end
```

Direct collection indices start at zero. `:Value()` copies the collection
membership into a one-based Lua table; the entities in it remain live objects.
Validate them again if you keep the table for later.

## Overloads

When one symbol has multiple call shapes, each shape is its own card with the
same name and a different argument list. For example,
[`render.LoadFont`](/cs2/api_reference/rendering/render#render-LoadFont) accepts
a built-in font preset or a font family/path with a size and optional settings.

```lua built-in font luaintelligence=true semantic="lua:cs2:cs2/api_reference/introduction/reading-these-docs:5:053a11a38d8f"
local font = render.LoadFont(render.EspFont.kRegular)
```

```lua family and size luaintelligence=true semantic="lua:cs2:cs2/api_reference/introduction/reading-these-docs:6:396ca5e1bfde"
local font = render.LoadFont("Arial", 16, render.FontEffect.kOutline)
```

<Tip>
  If two cards share a name, do not assume the first one is the only valid call. Compare their arguments before copying an example.
</Tip>

## Inheritance

Some object type sections show an **inherits** row with one or more class pills
under the heading.
That means the value has the documented behavior of those parent types too. For
example, `value.AtomicCollection` inherits `value.View`, which supplies `:Cast`
and inherits `:GetInstance` and `:GetSchemaType` from `value.Object`.
`console.Variable` inherits `console.Object` fields such as `name`, `flags`,
and `is_valid`.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/api_reference/introduction/reading-these-docs:7:3e0a395cd612"
local var = console.sv_cheats
if var.is_valid then
    print(var.name, " = ", var.value, " (flags ", var.flags, ")")
end
```

## Events pages

There are two event-related areas:

* [`events`](/cs2/api_reference/runtime/events) documents the event object API:
  `:Set`, `:Unset`, and `:Fire`;
* generated event pages such as [Cheat Events](/cs2/api_reference/events/cheat)
  document concrete callback names such as `render`, `pre_movement`, and
  `shutdown`.

Each event is a card whose signature shows the callback shape. Below it, the
argument's fields or values are listed the way you use them: `e.attacker` for a
payload object, `reason == "unload"` for a value the callback receives. Function
arguments with a fixed set of values list them the same way, as `name = "Text"`.
The `render` event takes a
callback with no arguments; `pre_movement` passes `cmd` (`UserCmd`) and
`player` (`simulation.Player`).

```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/introduction/reading-these-docs:8:8d748de81a51"
events.render(function()
    render.DrawLine(Vector2D(50, 50), Vector2D(100, 100), Color(255, 255, 255))
end)
```

```lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/introduction/reading-these-docs:9:b9e5e2eb503b"
events.pre_movement(function(cmd, player)
    if cmd.is_first_pass and cmd.in_jump.pressed then
        print("Jump at tick ", player.tickcount)
    end
end)
```

## Dot, colon, and field access

The displayed name tells you which Lua syntax to use:

<Columns cols={3}>
  <Card title="Dot" icon="dot" href="/cs2/api_reference/engine/entity#entity-GetLocalPawn">
    `entity.GetLocalPawn()` is a namespace function.
  </Card>

  <Card title="Colon" icon="corner-down-right" href="/cs2/api_reference/engine/entity#Entity-IsValid">
    `pawn:IsValid()` is a method on a value.
  </Card>

  <Card title="Field" icon="list" href="/cs2/api_reference/engine/console#consolevariable">
    `console.sv_cheats.value` is a documented object field.
  </Card>
</Columns>

Entity objects also allow raw schema field access. Those field names come from
[Dumped Data](/cs2/dumped_data/overview/overview), not from the API method list.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/api_reference/introduction/reading-these-docs:10:a0d17bab541f"
local pawn = entity.GetLocalPlayerPawn()
if pawn and pawn:IsValid() then
    print(pawn:GetHealth())
    print(pawn.m_iHealth)
end
```
