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

---
title: Panorama
icon: panels-top-left
sidebar_position: 6
---

# Panorama

CS2 draws its menus and HUD with Panorama, a UI engine whose scripts run on
JavaScript (V8). The [`panorama`](/cs2/api_reference/rendering/panorama)
namespace lets Lua read and change that JavaScript world: panels, the game's
JavaScript API objects, events, and functions you compile yourself. The Panorama
pages under Dumped Data list what the game registers, as dumped from a running
client.

<Columns cols={2}>
  <Card title="Panel ids" icon="list" href="/cs2/dumped_data/panorama/ids" arrow>
    Every panel id the game had when dumped, linked to its panel type.
  </Card>

  <Card title="panorama namespace" icon="code" href="/cs2/api_reference/rendering/panorama" arrow>
    The script's context, how values cross between Lua and JavaScript, `Compile` and events.
  </Card>
</Columns>

## Every script has its own context

The game's panels run their scripts in JavaScript contexts, one per layout.
Each Lua script that uses `panorama` gets a context of its own, created on first
use. It holds the same game API objects as every other context, plus `$` and
JavaScript's own globals, and it does not depend on the HUD or the main menu: it
works the same in the menu, on the loading screen and in a match.

When the script unloads, its context is deleted together with everything
registered from it: event handlers, panels made with `panorama.CreatePanel`, and
the functions compiled there. Nothing the script set up is left behind in the
game's UI.

## Three kinds of name

| You write                                   | What it is                                                      | Typed as                                                  |
| ------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------- |
| `panorama.GameStateAPI`, `panorama["$"]`    | A **global object**: a game API, read from the script's context | `panorama.GameStateAPI`, `panorama.dollar`                |
| `panorama.ids.Hud`, `panorama.ids.MainMenu` | A **panel id**: one panel's object                              | A field of `panorama.ids`, e.g. `panorama.panels.CSGOHud` |
| `panorama.panels.Label`                     | A **panel type**: the class of a panel's object                 | Annotations only; it is not a value                       |

Global objects and panel ids live in separate tables, so an id can never hide a
global of the same name.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/panorama:0:7c606a920964"
print(panorama.GameStateAPI.GetMapBSPName())  -- a global object

local menu = panorama.ids.MainMenu             -- a panel id
if menu then
    print(menu.paneltype)                      -- CSGOMainMenu
end
```

## Ids are not types

A panel id names one panel. A panel type names a class of panels. Valve reuses
type names as ids, so an id that spells a type's name is not necessarily a
panel of that type:

* `panorama.ids.Hud` is the panel of type `CSGOHud`.
* `panorama.ids.CSGOHud` is a plain `Panel` at the root of the HUD, the parent
  of `panorama.ids.Hud`.
* `MainMenu` and `CSGOMainMenu`, and `LoadingScreen` and `CSGOLoadingScreen`,
  follow the same pattern.

On [Panel ids](/cs2/dumped_data/panorama/ids), each id links to its panel type,
and a colliding id carries a note naming the id that has the type. At runtime,
`tostring` and the `paneltype` and `id` members tell you which panel you hold:

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/panorama:1:f324e746749b"
local hud = panorama.ids.Hud
if hud then
    print(tostring(hud)) -- panorama.Object<CSGOHud>
    print(hud.paneltype) -- CSGOHud
    print(hud.id)        -- Hud
end
```

## Panels

`panorama.ids.<Id>` returns the panel's JavaScript object, the same one the
game's scripts get from `FindChildTraverse`. It gives **nil** while no panel has
the id, so check the result before using it.

* **Reading** a name gives the panel's member (`visible`, `FindChildTraverse`, …).
* **Assigning** sets the member on the panel.
* **Calling** uses a dot, `hud.FindChildTraverse("HudRadar")`. A colon would pass
  the handle itself as the first argument.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/panorama:2:ca107947fcdf"
local hud = panorama.ids.Hud
if hud then
    local radar = hud.FindChildTraverse("HudRadar")
    if radar then
        radar.visible = false
    end
end
```

A panel's handle works while the context of that panel's scripts lives. When the
HUD is rebuilt, the old handle raises an error; read `panorama.ids.Hud` again.

## Narrow handles with panel types

Values JavaScript hands back, such as the result of `FindChildTraverse`, arrive
untyped. Tell the language server what they are with a panel type, then use that
type's members. Each panel type page lists only what the type adds to its base,
so check the base pages too.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/panorama:3:efd473933a41"
local hud = panorama.ids.Hud
if hud then
    local label = panorama.CreatePanel("Label", hud, "MyLabel") --[[@as panorama.panels.Label]]
    label.SetLocString("#SFUI_BuyMenu_Cannot_Afford")
end
```

`panorama.CreatePanel` works like `$.CreatePanel`, but the panel belongs to the
script and is deleted when the script unloads. A Lua function given for a panel
event such as `onactivate` runs when the event fires, the same as setting it
later with `panel.SetPanelEvent("onactivate", fn)`.

## Run JavaScript

`panorama.Compile` compiles a JavaScript function body and returns it as a
callable handle. Without a panel it compiles in the script's own context; with a
panel it compiles in the context of that panel's scripts, where
`$.GetContextPanel()` is the panel that owns the context.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/panorama:4:d53b6aa4a280"
local hud = panorama.ids.Hud
if hud then
    local owner = panorama.Compile("return $.GetContextPanel().id;", hud)
    print(owner())
end
```

Syntax and runtime errors raise Lua errors that name `lua://<script name>` and
the line in the source you compiled.

## Events

`panorama.RegisterForUnhandledEvent` calls a Lua function for an event no panel
handles, and `panorama.DispatchEvent` sends one. Both run in the script's
context, so the handler ends when the script unloads.

```lua luaintelligence=true lines=false semantic="lua:cs2:cs2/dumped_data/overview/panorama:5:21c6e8447aeb"
panorama.RegisterForUnhandledEvent("CSGOShowMainMenu", function()
    print("main menu shown")
end)

panorama.DispatchEvent("PlaySoundEffect", "UIPanorama.store_item_activated")
```

`$.RegisterEventHandler` throws in a script's context: the game would keep that
handler on the target panel after the script is gone. To handle one panel's
events, run the registration in that panel's own context with
`panorama.Compile(source, panel)`.

## Differences from plain Lua

<Steps>
  <Step title="Sequences become arrays" icon="braces">
    A table with keys 1 to n crosses as a JavaScript `Array` indexed from 0; any other table as a plain object. JavaScript arrays come back as handles indexed from 0, and `#` reads their `length`.
  </Step>

  <Step title="JavaScript errors are Lua errors" icon="triangle-alert">
    An exception thrown while Lua reads, assigns, calls or compiles raises a Lua error with the script and line it came from.
  </Step>

  <Step title="Everything ends with the script" icon="unplug">
    The script's context, its handlers, its panels and its callbacks end when it unloads. Scripts reload together, so saving a developer script ends them all.
  </Step>

  <Step title="Panel handles end with their context" icon="refresh-cw">
    A handle from `panorama.ids` works while that panel's context lives. Check for **nil** and look it up again after the UI rebuilds.
  </Step>
</Steps>

<Tip>
  Every `panorama.ids.<Id>` lookup walks the game's panels. Keep the handles a script reuses instead of looking them up every frame.
</Tip>

## Finding what to call

<Steps>
  <Step title="Pick the panel" icon="search">
    Search Panel ids. Each id links to its panel type.
  </Step>

  <Step title="Open its panel type" icon="app-window">
    The Panel types pages list each type's members; inherited members live on the base pages, down to `Panel`.
  </Step>

  <Step title="Use an API object" icon="braces">
    The API objects pages list game services such as `GameStateAPI`, `FriendsListAPI`, and `$`.
  </Step>
</Steps>
