Tutorials

The guide explains one concept per page. The tutorials go the other way: each one builds a complete, working system from start to finish, and uses whatever APIs it needs along the way. Each tutorial stands on its own, but they share conventions. Tutorials 2-4 also use the same clientr.hp / clientr.gold flags, so the HUD from tutorial 2 shows the gold spent in the shop and the damage taken from the blaster.

What you'll build

#	Tutorial	What it builds	Main APIs
1	Chat commands	A commands weapon with /help, /where, /roll, /nick and a staff-only /warp. Some commands are answered on the client; the rest are validated on the server.	onPlayerChats, triggerServer, triggerClient, player.hasright, player.warpto
2	HUD & message box	A health bar and gold counter drawn from clientr flags, plus a paged message window that any script can open.	findimg (screen mode), clientr, GUI controls, .on() events, measuretext, onKeyPressed
3	Shop & inventory	An item catalog in SQLite, per-player bags in a replicated collection, a shop window, a shopkeeper NPC and usable items.	opendatabase, collection, findweapon, NPC scripts, triggerAction, lib/ modules
4	Projectile gun	A blaster that fires level.shoot projectiles, a training dummy that takes hits, and player damage.	level.shoot, onShot, onShotAt, NPC state, clientr
5	NPCs with a shared class	A villager class that makes NPCs wander, answer chat and talk on a key press, plus an innkeeper that spawns a temporary merchant.	join(), this.move, onMovementFinished, triggerAction, putnpc
6	Day/night & torches	A server-driven world clock shared through a serverr flag, smooth clientside ambient light, and flickering torch NPCs.	serverr, setambient, drawaslight
7	Particle effects	A campfire with flames, smoke, wind and spark bursts, plus one-shot fireworks.	findimg(...).emitter, modifiers, continueafterdestroy
8	Leaderboard	SQLite scores published to a replicated collection, shown in a live-updating top-10 window.	opendatabase, collection, GUI

Before you start

Work through Getting started first. You should know how to:

• sign in to your server with GRC and join it in the game client;
• create a script in GRC's Weapons editor, with its Serverside and Clientside tabs, and save it;
• grant a weapon from the Players window.

Tutorials that use NPCs also need a level you can open in GRC's Level Editor.

Installing an example

Every tutorial shows each file it uses in full: expand the complete file blocks, or copy the snippets step by step. Each file's path tells you where it goes:

Path in the tutorial	Where to create it in GRC
weapons/<name>.ts	Weapons editor, the <name> entry's Serverside tab
weapons/<name>.client.ts	Weapons editor, the <name> entry's Clientside tab
classes/<name>.ts / .client.ts	Classes editor
lib/<name>.ts / .client.ts	Lib editor
<name>.ts (no folder)	Scripts editor
npcs/<name>.npc.ts	Not a file: the serverside script of an NPC in the Level Editor
npcs/<name>.npc.client.ts	Not a file: the clientside script of that NPC

To install one:

1. Create the scripts. In each editor, right-click the folder at the top of the file tree, choose New file…, paste the code and Save. Create lib/ files first, since other scripts import them.

2. Place the NPCs (only for tutorials with an npcs/ folder). NPC scripts are stored in the level, not in scripts/. Open the level in the Level Editor and add an NPC. Paste <name>.npc.ts into its serverside script and <name>.npc.client.ts into its clientside script, then save the level. The .npc.ts suffix is only a naming convention of these docs.

3. Grant the weapons. A player only runs a weapon once they've been granted it. To test right away, right-click yourself in the Players window and choose Grant weapon…. For weapons that every player should have, add them to startWeapons in the Server Options window and click Apply:

   "startWeapons": ["commands", "hud", "messagebox"]

   Your server's login.ts grants these to every player when they log in. Scripts can also grant weapons with player.addWeapon('name'). See Weapons.

4. Reload. Saving a script in GRC recompiles and hot-reloads it. Players who already have the weapon get the new clientside half straight away.

If a script doesn't seem to run, check the reload bar above the editor and the server log in GRC's main window. Compile errors and serverside echo() output appear there. See Debugging & tooling for seeing clientside output.

Every example is tested

The code in these tutorials is type-checked against the current scripting API every time the docs are built, so it compiles on your server as written.