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

---
title: Anatomy
description: Understand the extension folder, manifest, entry point, and reload model.
icon: folder-tree
sidebar_position: 1
---

# Anatomy

An **extension** contains Lua files that Neverlose loads at runtime. A local
developer extension lives in a folder with a manifest, a `main.lua` entry point,
and any extra files you split your logic across.

<Note>
  **The folder name is your local extension's display name.** It is what shows
  up in the Extensions list. There is no `name` field in the manifest.
</Note>

## Where extensions live

Local developer extensions live on disk in your Neverlose data folder. Enable
**Developer mode** in the cheat's settings to show them in the Extensions list:

```plaintext lines=false
…/Counter-Strike Global Offensive/game/bin/win64/neverlose/extensions
```

Once an extension appears in the list, **Open Folder** in its right-click menu
opens its directory. If Visual Studio Code is installed, **Open with Code**
opens the same folder directly in your editor.

## Minimal layout

A minimal extension is just two files:

<Tree.Folder name="example" icon="folder" defaultOpen>
  <Tree.File name="extension.json" icon="file-cog" />

  <Tree.File name="main.lua" icon="file-braces-corner" />
</Tree.Folder>

<Columns cols={3}>
  <Card title="extension.json" icon="file-cog">
    The manifest. It declares the Lua language and any modules listed
    in [Requirements](/cs2/api_reference/extensions/requirements).
  </Card>

  <Card title="main.lua" icon="file-braces-corner">
    The entry point. Neverlose runs this file each time the extension loads
    or reloads.
  </Card>

  <Card title="extra files" icon="folder-tree">
    Optional Lua modules, assets, localization, or shared helpers. Organize them
    however the extension needs.
  </Card>
</Columns>

An optional `.neverloseignore` file controls which files are included when
publishing. It does not prevent your extension from reading those files during
local development. Directories whose names start with a dot, such as `.git`,
`.vscode`, and the `.nl` snapshot cache, are excluded from published bundles.

## Create the extension

<Steps>
  <Step title="Enable Developer mode" icon="settings">
    Enable **Developer mode** in the cheat's settings so local extensions are
    available in the **Extensions** tab.
  </Step>

  <Step title="Create the folder and files" icon="folder-plus">
    Create a folder under `…/neverlose/extensions/`, then add `extension.json`
    and a nonempty `main.lua`. Use the manifest and entry-point examples below
    to get started.
  </Step>

  <Step title="Enable the extension" icon="power">
    Open the **Extensions** tab and enable your extension. Use **Open Folder**
    or **Open with Code** from its right-click menu for subsequent edits.
  </Step>
</Steps>

Turning off **Developer mode** unloads local extensions. Turn it back on and
enable the extensions you want to run again.

## The manifest

Every extension has an `extension.json` at its root. The loader reads two
fields: the required language and an optional list of requirements.

<Tabs>
  <Tab title="Fields" icon="list">
    <SchemaField name="language" type="string" required>
      The VM the extension runs on. Currently only `"lua"` is supported.
    </SchemaField>

    <SchemaField name="requirements" type="string[]">
      Modules your extension depends on. Omit this field or use an empty array
      if you have none.
    </SchemaField>
  </Tab>

  <Tab title="Minimal" icon="file-cog">
    Use this when the extension has no external dependencies.

    ```json extension.json
    {
      "language": "lua",
      "requirements": []
    }
    ```
  </Tab>

  <Tab title="With requirements" icon="puzzle">
    Declare native, marketplace, or local dependencies here. The marketplace
    name and version below are illustrative; replace them with a published
    library you use, and create the `shared` local extension before loading.

    ```json extension.json
    {
      "language": "lua",
      "requirements": [
        "ffi",
        "neverlose/example-library:5",
        "local/shared"
      ]
    }
    ```
  </Tab>
</Tabs>

<Card title="Manifest rules" icon="list-check">
  * **Keep it valid JSON.** No comments and no trailing commas.
  * **Save as UTF-8.** Neverlose strips a leading byte-order mark from the root
    manifest when reading it locally and preparing an upload.
  * **Leave old metadata out.** Older examples sometimes show `name` and `icon`
    keys; those are ignored.
  * **Edit it directly or through Settings.** The extension's **Settings**
    dialog writes the same `requirements` array.
</Card>

## The entry point

Each time the extension loads, Neverlose runs `main.lua` top to bottom. You
do not write a manual game loop. Register callbacks on
[events](/cs2/api_reference/runtime/events), and the cheat calls them for you:

```lua main.lua
-- my-extension
-- runs once when the extension is enabled

events.render:Set(function()
    -- runs every frame on the render thread
end)
```

## Hot reload

Neverlose checks local extensions for changes every **five seconds**. An
**enabled** extension reloads after a detected change while the **game window
is focused and the menu is open**. After saving in your editor, return to the
game and open the menu to let it reload. Reloading runs `main.lua` again.

Enabling, disabling, or reloading another extension can also rerun `main.lua`
for active extensions sharing its Lua runtime. Keep setup safe to repeat and
use `events.shutdown` to restore temporary changes outside your extension.

Disabled extensions pick up edits when you next enable them. Directories whose
names start with a dot are excluded from reload checks; `.neverloseignore`
rules do not exclude files from these checks.

<Columns cols={2}>
  <Card title="Requirements" icon="puzzle" href="/cs2/api_reference/extensions/requirements">
    Learn how `requirements` map to native modules, marketplace packages, local
    extensions, and your own Lua files.
  </Card>
</Columns>
