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

---
title: Lifecycle and Events
icon: radio
sidebar_position: 3
---

# Lifecycle and Events

Neverlose scripts are event-driven. You do not write a permanent `while true`
loop. Put setup in `main.lua`, subscribe to events, and let Neverlose call your
callbacks at the right time.

## main.lua runs on load

Use the top level of `main.lua` for values that should be created once per load:

```lua main.lua luaintelligence=true semantic="lua:cs2:cs2/api_reference/extensions/lifecycle-and-events:0:49a5c7640ddb"
local font = render.LoadFont(render.EspFont.kRegular)
local show_names = ui.AddTab("Lua"):AddGroup("Example"):AddToggle("Show names")

events.render(function()
    if not show_names.value then
        return
    end

    for controller, pawn in entity.IteratePlayers(true, false) do
        if pawn:IsValid() then
            local pos = projection.WorldToScreen(pawn:GetAbsOrigin())
            if pos then
                render.DrawText(pos, Color(255, 255, 255), font, "c", controller:GetPlayerName())
            end
        end
    end
end)
```

Reloading the extension runs the file again. Enabling, disabling, or reloading another extension in the same Lua runtime can also trigger this setup.
Keep it safe to repeat, and restore temporary external changes in `events.shutdown`.

## Render code belongs in events.render

Most functions in [`render`](/cs2/api_reference/rendering/render) write to the
current frame's draw list. Call them from [`events.render`](/cs2/api_reference/events/cheat#render).

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/api_reference/extensions/lifecycle-and-events:1:3cfa690eed0d"
local font = render.LoadFont(render.EspFont.kBold)

events.render(function()
    local screen = engine.GetScreenSize()
    if not screen then
        return
    end

    render.DrawText(screen / 2, Color(130, 165, 255), font, "c", "Center text")
end)
```

If you need to calculate data outside render, store it in locals and draw the
latest value from the render callback.

## Movement code belongs in movement events

`pre_movement` and `post_movement` surround movement processing;
`createmove` runs before command finalization. Their callbacks receive the
current [`UserCmd`](/cs2/api_reference/input/cmd#usercmd) and a
[`simulation.Player`](/cs2/api_reference/input/cmd#simulationplayer).
Inspect these values inside the callback; clone a simulation before changing
or advancing it.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/api_reference/extensions/lifecycle-and-events:2:074377a554ab"
events.pre_movement(function(cmd, player)
    if cmd.is_first_pass and cmd.in_jump.pressed then
        print("Jump pressed at simulation tick ", player.tickcount)
    end
end)
```

Use [`events.input_poll`](/cs2/api_reference/events/cheat#input_poll) for live
input before it becomes a command. Its `input.InputPollContext` uses boolean
`in_*` fields; command fields such as `cmd.in_jump` are button handles with
`down`, `pressed`, and `released` properties.

Open the [Cheat Events](/cs2/api_reference/events/cheat) page for callback names
and payload types.

## Delayed work

For "do this later" behavior, use [`time.Schedule`](/cs2/api_reference/runtime/time#time-Schedule)
instead of blocking the script.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/api_reference/extensions/lifecycle-and-events:3:5cae76dd787d"
print("Now")

time.Schedule(1.0, function(message)
    print(message)
end, "One second later")
```

Callbacks should return quickly. Heavy work in a per-frame event will affect the
same frame budget as your game and cheat UI.

## Shutdown cleanup

Use [`events.shutdown`](/cs2/api_reference/events/cheat#shutdown) when your
script changes state that should be restored manually.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/api_reference/extensions/lifecycle-and-events:4:4a0929d483fb"
local showfps = console.cl_showfps
if showfps.is_valid then
    local old_value = showfps.value
    showfps.value = 1

    events.shutdown(function()
        if showfps.is_valid then
            showfps.value = old_value
        end
    end)
end
```

Normal event callbacks and UI created by the script are removed when the script
reloads. Shutdown is for things you changed outside that automatic ownership,
such as convars or library state.

## Choosing an event

<CardGroup cols={2}>
  <Card title="Draw every frame" icon="brush" href="/cs2/api_reference/events/cheat#render" arrow>
    Use `events.render`; it is the safe place for most `render.*` calls.
  </Card>

  <Card title="Change movement" icon="move" href="/cs2/api_reference/events/cheat#pre_movement" arrow>
    Use movement events that pass a `UserCmd` and `simulation.Player`.
  </Card>

  <Card title="React to game events" icon="zap" href="/cs2/api_reference/events/game" arrow>
    Use generated game event pages for payload fields such as user IDs, weapon names, or positions.
  </Card>

  <Card title="Library communication" icon="radio" href="/cs2/api_reference/runtime/events#eventseventtraits" arrow>
    Subscribe with `:Set`, detach with `:Unset`, and use `:Fire(...)` for your own event names. Scripts cannot fire host-owned events.
  </Card>
</CardGroup>
