How to use scripts

Run Arcane Lua scripts from the overlay. You do not install Lua, Node, or Python.

To write your own, see the script developer guide.

Quick start

1. Start official Tibia and inject Arcane.
2. Overlay → SCRIPTS.
3. Open folder is %USERPROFILE%\Documents\SharpTib\scripts.
4. Leave Auto-run off the first time. Load 01_hello.lua and check LOGS.
5. Reload all after you edit a file on disk.

More modules: overlay Community Store. Installed store modules live in scripts\store\<id>\ — edit those files in place. To publish your own, see upload to the Community Store.

Do not point Config scripts_folder at a second copy of the same scripts.

Overlay

• X / Hide / minimize on the main menu closes only that window. Lua HUDs stay.
• Insert hides every overlay surface at once (same as game.overlay.hide).
• The overlay steals mouse and keyboard only while the cursor is over an Arcane window.

Planner (optional)

Hunt zones are drawn in the browser, not in a Lua file.

1. Map tab → Download Planner if the exe is missing or outdated (or drop SharpPlanner.exe into Documents\SharpTib\planner\ and map tiles into Documents\SharpTib\maps\). A running planner is closed first, then replaced.
2. Port 38574 → Connect to Planner → Open Planner. Closing the game also closes a planner the overlay started. Disconnect leaves it running.

Details: sharing and packs.

Overlay controls

Control	What it does
Reload all	Rescan .lua files and reload them
Open folder	Opens Documents\SharpTib\scripts
Auto-run	Load scripts at inject and when files change. Off by default on each inject
Community Store	Browse, install, and upload community modules
Game MCP port	Config tab. Default 38472. Localhost only

Runtime errors quarantine the module and show a crash-report path on the Scripts tab.

Open this folder in an IDE

1. Inject once → Scripts → Open folder.
2. Open that folder as the workspace in Cursor, VS Code, Claude Code, Codex, or Gemini CLI.
3. Restart MCP / reload the window and enable Game MCP (game-mcp) if asked.

Client	Seeded file
Cursor	.cursor/mcp.json
VS Code Copilot	.vscode/mcp.json
Claude Code	.mcp.json
Codex	.codex/config.toml
Gemini CLI	.gemini/settings.json

Web ChatGPT cannot reach 127.0.0.1. Do not port-forward Game MCP or the planner.

FAQ

A script did nothing in-game
Read the log. Talk needs a logged-in character. Trade needs an open NPC window. Auto-run starts off every inject.

The editor does not show Game MCP
The workspace must be Documents\SharpTib\scripts, not the git repo and not AppData.

How do I upload my script to the store
Overlay → SCRIPTS → select the file → Upload..., or open Community Store → + Upload Script. Step by step: upload to the Community Store.