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

---
title: Overview
description: Write Lua extensions for Counter-Strike 2 with the Neverlose scripting API.
icon: compass
sidebar_position: 1
---

# CS2 Scripting

Neverlose lets you extend Counter-Strike 2 with your own **Lua extensions**:
self-contained scripts that hook into the game loop, draw to the screen, read
the entity system, and add their own controls to the cheat menu. This section
has everything you need to write them, from the extension layout to the exact
name, arguments, and return value of every function you call from `main.lua`.

<Note>
  New here? The fastest path is [Getting Started](/cs2/api_reference/introduction/getting-started) → [Anatomy](/cs2/api_reference/extensions/anatomy) → [Lifecycle and Events](/cs2/api_reference/extensions/lifecycle-and-events) → [Lua Crash Course](/cs2/api_reference/tutorials/lua-crash-course). Then keep the reference pages open while you write.
</Note>

## Start here

<Card title="Getting Started" icon="rocket" href="/cs2/api_reference/introduction/getting-started" arrow>
  Unlock Developer mode, create your first extension, publish it on the market, and set its price.
</Card>

<CardGroup cols={2}>
  <Card title="Anatomy" icon="folder-tree" href="/cs2/api_reference/extensions/anatomy" arrow>
    The extension folder, manifest, `main.lua` entry point, and hot reload model.
  </Card>

  <Card title="Lifecycle and Events" icon="radio" href="/cs2/api_reference/extensions/lifecycle-and-events" arrow>
    How `main.lua`, callbacks, render-only drawing, delayed work, and shutdown fit together.
  </Card>

  <Card title="Requirements" icon="puzzle" href="/cs2/api_reference/extensions/requirements" arrow>
    Native, marketplace, and local modules, and splitting your code across files.
  </Card>
</CardGroup>

## What to open first

<CardGroup cols={2}>
  <Card title="events" icon="bolt" href="/cs2/api_reference/runtime/events" arrow>
    Run code on render, movement, unload, game messages, and custom library events.
  </Card>

  <Card title="render" icon="brush" href="/cs2/api_reference/rendering/render" arrow>
    Draw text, lines, rectangles, images, gradients, clips, and other frame-only UI.
  </Card>

  <Card title="ui" icon="layout-grid" href="/cs2/api_reference/rendering/ui" arrow>
    Add tabs, groups, controls, color pickers, callbacks, and references to menu items.
  </Card>

  <Card title="entity" icon="users" href="/cs2/api_reference/engine/entity" arrow>
    Read players, pawns, weapons, game rules, world entities, and schema-backed fields.
  </Card>

  <Card title="schema" icon="list-tree" href="/cs2/api_reference/engine/schema" arrow>
    Inspect Source 2 classes, fields, offsets, field types, and enum tables from Lua.
  </Card>

  <Card title="console" icon="terminal" href="/cs2/api_reference/engine/console" arrow>
    Read or change convars and call console commands through typed objects.
  </Card>
</CardGroup>

## Browse by category

The reference groups related APIs together:

* **Runtime**: events, delayed work and clocks in [time](/cs2/api_reference/runtime/time), utilities, cloud access, and hardware monitoring.
* **Engine**: entities, [engine state](/cs2/api_reference/engine/engine), schema reflection, [schema values](/cs2/api_reference/engine/value), console, traces, and memory helpers.
* **Input & Movement**: [input polling](/cs2/api_reference/input/input), commands and player simulation in [cmd](/cs2/api_reference/input/cmd), and motion helpers.
* **Rendering & UI**: drawing, menu controls, [indicators](/cs2/api_reference/rendering/indicators), effects, ESP, view overrides, and Panorama.
* **mathlib**: vectors, angles, colors, matrices, and geometry helpers.
* **Data & Storage**: database, filesystem, JSON, and MessagePack.
* **Networking**: HTTP, network-channel statistics, and protobuf messages.
* **Lua & LuaJIT**: standard Lua and LuaJIT libraries and their available extensions.

## Your entry point is main.lua

Neverlose runs your extension's `main.lua` when the extension is loaded or
reloaded. Do setup once at the top of the file, then attach callbacks for work
that must happen later.

```lua main.lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/introduction/overview:0:c8510bc6a5bb"
local font = render.LoadFont(render.EspFont.kRegular)

events.render(function()
    render.DrawText(
        Vector2D(20, 20),
        Color(255, 255, 255, 255),
        font,
        nil,
        "Hello from Neverlose"
    )
end)
```

This is the normal shape of a script:

<Steps>
  <Step title="Create values once" icon="box">
    Load fonts, find UI controls, define helper functions, and keep state in locals.
  </Step>

  <Step title="Subscribe to events" icon="radio">
    Put per-frame and per-tick work in callbacks such as `events.render` and `events.pre_movement`. Scripts can also send each other events under names of their own; see [events](/cs2/api_reference/runtime/events).
  </Step>

  <Step title="Read live data inside callbacks" icon="activity">
    Entities, convars, screen size, and game state can change every frame. Fetch or validate them close to where you use them.
  </Step>

  <Step title="Clean up when needed" icon="refresh-cw">
    When you change something outside your script, such as a convar, register the undo with `defer` right there. It runs when the script unloads or reloads. Use `events.shutdown` when you need to know why the script is stopping.
  </Step>
</Steps>

## Lua names you will see often

Create common value types with the same names shown in API return types:

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/api_reference/introduction/overview:1:6612e97f69ee"
local pos = Vector(0, 0, 64)
local point = Vector2D(20, 20)
local view = QAngle(0, 90, 0)
local white = Color(255, 255, 255, 255)
```

Lua names are case-sensitive. Use the documented spelling, including
`Vector`, `Vector2D`, `QAngle`, and `Color` for constructors and PascalCase
functions such as `entity.GetLocalPawn()` and `render.DrawText()`. Event names
and data fields keep their documented spelling, such as `events.render` and
`console.cl_showfps.value`.

## API pages vs Dumped Data

Use **API Reference** for callable Lua names: functions, methods, callbacks,
classes, modules, and value types.

Use [Dumped Data](/cs2/dumped_data/overview/overview) when you need Source 2
names: schema classes, raw field names, offsets, enum values, convars, or
commands.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/api_reference/introduction/overview:2:f6f09c63abce"
local pawn = entity.GetLocalPlayerPawn()

if pawn and pawn:IsValid() then
    print(pawn:GetHealth())  -- API helper
    print(pawn.m_iHealth) -- raw Schema field
end
```

<Tip>
  Prefer helper methods when they exist. Raw schema fields are useful for data the API does not wrap directly.
</Tip>

## Learn the language

New to Lua, or want to go deeper with FFI and LuaJIT? These guides take you from
the basics to performance-critical native interop.

<CardGroup cols={3}>
  <Card title="Lua Crash Course" icon="graduation-cap" href="/cs2/api_reference/tutorials/lua-crash-course" arrow>
    Variables, control flow, functions, tables, metatables, and modules in one page.
  </Card>

  <Card title="FFI Crash Course" icon="binary" href="/cs2/api_reference/tutorials/ffi-crash-course" arrow>
    Call into C from Lua to reach engine internals the high-level API doesn't expose.
  </Card>

  <Card title="Advanced LuaJIT" icon="zap" href="/cs2/api_reference/tutorials/advanced-luajit" arrow>
    Squeeze performance out of hot paths with LuaJIT-specific techniques.
  </Card>
</CardGroup>

<Tip>
  All your callbacks share a single Lua state. LuaJIT runs your script on one thread, not in parallel, so a slow callback stalls the frame. Keep per-frame work light.
</Tip>

## Next pages

<CardGroup cols={2}>
  <Card title="Reading API Pages" icon="book-open" href="/cs2/api_reference/introduction/reading-these-docs" arrow>
    How to read signatures, tabs, examples, optional arguments, methods, and type links.
  </Card>

  <Card title="Globals and Modules" icon="package" href="/cs2/api_reference/extensions/globals-and-modules" arrow>
    What is available directly, what must be loaded with `require`, and how modules differ from globals.
  </Card>

  <Card title="Dumped Data Overview" icon="database" href="/cs2/dumped_data/overview/overview" arrow>
    How Schema and Console pages turn into practical entity and convar code.
  </Card>

  <Card title="Lua Intelligence" icon="sparkles" href="/cs2/api_reference/introduction/lua-intelligence" arrow>
    Hover cards, signatures, diagnostics, and API links in the code examples on these pages.
  </Card>
</CardGroup>
