Script API Reference

How to read this page#

Vastopia server scripts are C# files compiled by the game server at startup. They talk to the game through a small set of script API classes that wrap the engine safely. This page lists that surface. The signatures and descriptions below are taken from the server source and from the same generated API database the Script Editor uses for autocomplete (script_api.json), so what you see here is what the compiler sees.

Three places give you the same information while you work:

• Script Editor, API panel - the bottom-right card lists every root object (player, npc, obj, ctx, ScriptWorld, GameData, ...) with its members. Type in Search API... to filter, select a member to read its signature, double-click to insert it at the caret.
• Script Editor, API Files menu - opens any API type as a read-only, syntax-highlighted reference tab (ScriptPlayer (API) and so on).
• Autocomplete - typing player. in a script offers the members below with their one-line summaries.

Two concepts are used everywhere, so read them first.

Roots: the objects your script receives#

Units, positions and ticks#

• Positions are System.Numerics.Vector3 with the server convention (X, Y, Z) = (east-west world units, north-south world units, height layer). The second horizontal axis is stored in Position.Y, and Position.Z is the height-layer index (0 = terrain, 1-4 = stacked height layers, see Height layers). Methods that take coordinates name the plane axes x and z (Teleport(region, x, z, heightLayer)) or x, y, z (ScriptWorld.SpawnNpc(npcId, region, x, y, z)); in both cases the last value is the height layer.
• One tile is 0.5 world units. world = tile * 0.5. Spawn coordinates should be multiples of 0.5 so footprints sit on whole tiles. See Coordinate system.
• Time is measured in game ticks. 4 ticks is approximately 1 second. Every delay, respawn time and scheduler interval below is in ticks.
• Object positions are the south-west corner of the footprint; the footprint extends east (+X) and north.

Usings you never write#

The server prepends a fixed block of using directives to every script and module before compiling it, so ScriptPlayer, ModuleLoader, TaskScript, Vector3, List<T> and Task resolve without any using of your own. The full list is the one written to server/_VastopiaGlobalUsings.g.cs by generate_script_project (see IDE setup). One side effect worth knowing: using static GameData brings Random(int, int) into scope, so write System.Random.Shared when you want .NET's random class.

Script base classes#

A script is a class that extends one of these bases or implements one of these interfaces. Override only the hooks you need; the default for every click-handling bool hook is false ("not handled"), for the task hooks OnStart / OnTick it is true ("keep going"), and for every stat override it is -1 ("use the next fallback"). Which folder a file lives in decides which registry picks it up. Entity-bound scripts bind to IDs either through their NpcIds / ObjectIds / ItemIds array or through server/data/script_bindings.json (sections npcs, npc_combat, objects, items, equipment, each mapping an entity id to a script path), which the editor writes when you pick a script on an NPC, object or item. See NPC, object and interaction scripts for the workflow.

EquipmentStats is a record with nine integer bonuses: AccuracyMelee, AccuracyRanged, AccuracyMagic, StrengthMelee, StrengthRanged, StrengthMagic, DefenceMelee, DefenceRanged, DefenceMagic; EquipmentStats.Empty is all zeros.

NpcScript, NpcCombatScript and ObjectScript also give you per-instance variables that live as long as that NPC or object is in the world: SetVar(entity, key, value), T GetVar<T>(entity, key, defaultValue), bool HasVar(entity, key). They are keyed by the entity's server Index, and cleaned up when it despawns. They are not saved; for anything that must survive a restart use player.SetVar or a WorldStore (below).

ScriptPlayer#

ScriptPlayer is the player-facing API and is passed directly to all script methods.

Identity#

Position and movement#

Instances and parties#

Health#

Inventory#

ItemContainer (used for inventory and bank) exposes Capacity, UsedSlots, FreeSlots, IsFull, IsEmpty, Item? GetItem(int slot), bool AddItem(Item item), Item? RemoveItem(int slot), bool RemoveItem(int itemId, int amount), int GetItemAmount(int itemId), bool HasItem(int itemId, int amount = 1), List<Item> GetItems(), int FindEmptySlot(), bool SwapItems(int slot1, int slot2) and void Clear().

Bank#

Animation and effects#

Interfaces#

Interfaces are the screens built in the GUI editor. Every call below sends a packet to this player's client; nothing runs on the client itself.

Chat and dialogue#

For branching conversations authored without code, see the Dialogue editor.

Combat#

Persistent variables#

Per-player key/value storage that survives logout and server restarts; it is saved with the character alongside inventory and skills. Use it for quest flags, unlocks, cooldown stamps and personal progress. Keys are case-insensitive; namespace them by convention ("quest.dragonslayer.stage"). For state shared by many players, use a WorldStore instead.

Scheduling#

The returned ActionTask has Stop(), ResetCountdown(), GetCountdown(), IsRunning and ExecutionCount.

ScriptSkills#

Reached through player.Skills. Skill names are the ones defined in Skills (skills_config.json); the server also generates a SkillId class with one constant per skill for the integer overloads.

ScriptParty#

Obtained from player.Party or player.CreateParty().

ScriptNpc#

The read-mostly wrapper returned by ScriptWorld lookups.

ScriptWorld#

All members are static - no player reference needed.

ScriptInstance#

Instances are isolated copies of a region for raids, minigames and private boss fights. They auto-destroy (despawning their NPCs, objects and ground items) when the last player leaves.

await ScriptInstance.Create("boss", raidId, copyDefaults: false);
await ScriptInstance.SpawnNpc(raidId, BOSS_ID, "boss", 20, 20, 0);
await player.Teleport("boss", 20, 25, 0, raidId);

ScriptLoot#

Rolls the drop tables authored in the Loot Tables tool (server/schemas/Drops/*). Entity-bound tables (npc_drops, npc_table_drops, npc_wheel_drops, keyed by NPC ids) are rolled on death by the drop module; standalone Misc tables (misc_drops, misc_table_drops, misc_wheel_drops, keyed by a table_id string) are what you roll from code for chests, minigame rewards and quest prizes. Which file a table lives in decides how it rolls: independent tables roll every entry's 0-100 chance separately, named sub-tables roll once each and pick rolls items, and wheel tables spin rolls times over weighted groups.

WorldStore#

A named, persistent key/value store for world state - minigame scores, leaderboards, world events, anything not owned by a single player. Get one with ScriptWorld.GetStore("pest_control"); names are normalised to [a-z0-9_-], so use one store per system. Values are strings with typed reads; keys are case-insensitive. Writes mark the store dirty; dirty stores are flushed every few seconds and everything is flushed on shutdown or crash. Each flush writes data/saves/world/{name}.json and, on platform servers with a database configured, the game's world_data collection.

var store = ScriptWorld.GetStore("pest_control");
store.Increment("points." + player.Username, 5);
int points = store.GetInt("points." + player.Username, 0);

GameData and GameEnums#

GameData is a static helper; because the prelude includes using static GameData, you may call GetItem(12) or Vec3(1, 2, 0) with or without the GameData. prefix.

GameEnums exposes three CombatStyle values: GameEnums.Melee, GameEnums.Ranged, GameEnums.Magic.

Data tables#

Every schema created in the Script Editor (server/schemas/<Category>/<name>/<name>.json plus <name>_data.json) or by a tool is readable at runtime:

var prices = GameData.GetData("shop_prices");
var row = prices?.FindById(itemId);
int cost = row?.GetInt("price", 100) ?? 100;

TaskContext#

Carries the entity references from the trigger that started a task, and is the same object across OnStart, OnTick and OnStop. Triggers are defined per task in the Tasks editor; the trigger types the server parses are object_click, npc_click, item_click, command, location_enter, item_on_object, item_on_npc, item_on_item, server_startup, player_join, npc_spawn and object_spawn - of these, location_enter is read from the task data but never fired.

Entity types#

Hooks hand you engine entities rather than wrappers. The members you will use:

WorldObject#

NPC#

Modules#

Modules are long-lived systems in server/modules/ (one class per file, compiled separately, loaded in dependency order). They are the place for shared logic, because each script file compiles alone and cannot see helpers declared in another script file. See Events and systems.

public class FishingModule : ModuleBase<FishingModule>
{
    public override string Id => "fishing";
    public override string Name => "Fishing";

    public int RollCatch(int level) => GameData.Random(1, level + 2);
}

// From any script:
var fishing = ModuleLoader.Module<FishingModule>();
int fish = fishing?.RollCatch(player.Skills.GetLevel("Fishing")) ?? 0;
// or, because the module declares ModuleBase<FishingModule>:
FishingModule.Instance?.RollCatch(5);

A game module whose Id matches a pre-compiled platform module replaces it; two game modules with the same Id are a conflict and the second is skipped. A module listed as disabled in server/data/systems.json is never loaded, even if its file is present.

Events#

Modules (and scripts) subscribe to the event bus: EventBus.Instance.Subscribe<T>(Action<T> handler, EventPriority priority = EventPriority.NORMAL, bool ignoreCancelled = true) (an async Func<T, Task> overload exists), Unsubscribe, Publish<T>(T evt) and PublishAsync<T>. Every event derives from GameEvent with IsCancelled, Timestamp, Cancel() and Uncancel(); events marked IUncancellable cannot be cancelled. Priorities run LOWEST (0), LOW, NORMAL, HIGH, HIGHEST, MONITOR (5).

Field-by-field detail for each event is in Events and systems. Player commands should be ICommandScript classes, not PlayerChatEvent parsers - see Commands.

Enums#

With AI (MCP)#

get_script_api returns this same surface to an assistant: call it with no argument for the index of API classes and script base classes, or with a class name (ScriptPlayer, NpcScript) for the full member list with signatures, summaries and which members are overridable hooks. read_server_script, write_server_script, move_server_script, delete_server_script and list_server_scripts work on the files themselves, and generate_script_project writes the IDE companion described in IDE setup. The full tool list is in the MCP tools reference.