Latest revision as of 16:39, 22 August 2025

RuneScript Reference/Scripting Tutorial

Disclaimer: this document is being written by a relative noob in an effort to document my findings and iron out any incorrect notions or faulty assumptions. It is not complete and may be (read: probably is) egregiously wrong in certain areas. Continue at your own peril!

Introduction

This document aims to acquaint new contributors with the basics of writing RuneScript as used by Lost City. Before reading, you are expected to have:

Decent reading comprehension
- Go slowly and read each section multiple times if needed
Willingness to ask for help
- Lost City is learning community and we are here to assist
Most importantly - a winning attitude!
- If you get confused, ask a question and come back to the problem later

While not strictly required, having a working development environment set up on your computer would be a great advantage. You will be best able to follow along with the tutorial if you have:

Lost City's server set up and running for development on your local machine
- If you need help with this please visit #setup-help in Discord or make a post on the forum!
Your preferred text editor installed and ready
- VS Code is recommended because there is an extension for RuneScript syntax highlighting available.

Knowledge of basic programming fundamentals (variables, functions) will also help but is by no means required.

RuneScript

RuneScript files are written as plain text with the extension . RuneScript files are placed under `./data/src/scripts` in the server's source tree and are further organized by various criteria (area, quest, skill, etc).

The Lost City game server is capable of hot-reloading RuneScript files as you change them, meaning you can follow along with this tutorial and see your changes appear in-game in real time!

To learn the basics of RuneScript, continue with the next page of the tutorial where we examine triggers.

Next Page || Browse all Scriptref pages

@@ Line 1: / Line 1: @@
 [[Category:Scriptref]]
+'''[[:Category:Scriptref|Browse all Scriptref pages]]'''
 = RuneScript Reference/Scripting Tutorial =
-'''[[:Category:Scriptref|Go to the Table of Contents]]'''<blockquote>Disclaimer: this document is being written by a relative noob in an effort to document my findings and iron out any incorrect notions or faulty assumptions. It is not complete and may be (read: probably is) egregiously wrong in certain areas. Continue at your own peril!</blockquote>
+<blockquote>Disclaimer: this document is being written by a relative noob in an effort to document my findings and iron out any incorrect notions or faulty assumptions. It is not complete and may be (read: probably is) egregiously wrong in certain areas. Continue at your own peril!</blockquote>
 == Introduction ==
 This document aims to acquaint new contributors with the basics of writing RuneScript as used by Lost City. Before reading, you are expected to have:
-* Decent reading comprehension, go slowly and read each section multiple times if needed
+* Decent reading comprehension
-* Willingness to ask for help, Lost City is learning community and we are here to help
+** Go slowly and read each section multiple times if needed
-* Most importantly - a winning attitude! If you get confused, ask a question and come back to the problem later
+* Willingness to ask for help
+** Lost City is learning community and we are here to assist
+* Most importantly - a winning attitude!
+** If you get confused, ask a question and come back to the problem later
 While not strictly required, having a working development environment set up on your computer would be a great advantage. You will be best able to follow along with the tutorial if you have:
@@ Line 25: / Line 29: @@
 The Lost City game server is capable of hot-reloading RuneScript files as you change them, meaning you can follow along with this tutorial and see your changes appear in-game in real time!
-To learn the basics of RuneScript, continue with the next section of the tutorial where we examine '''triggers''': [[Scriptref_Triggers]]
+To learn the basics of RuneScript, continue with the next page of the tutorial where we examine '''triggers'''.
-=== Procedures, Commands, and Labels ===
+'''[[Scriptref_Triggers|Next Page]] || [[:Category:Scriptref|Browse all Scriptref pages]]'''<blockquote></blockquote>
-There are a few more trigger types to go over. These are slightly more complex but will ultimately make your life easier as they allow a scriptwriter to stay organized and avoid code reuse.
-Procedures, commands, and labels are simply triggers that have been given names and may be called from within other triggers. Often, parameters will be used to dictate the precise function of a given procedure/command/label.
-The intent is for a scriptwriter to utilize procedures/commands/labels _inside_ the scripts and triggers that they are writing.
-==== Procedures ====
-Procedures are prefixed with `~` when calling. For example:
-```ts
-[opnpc1,border_guard_lumby]
-~chatnpc("<p,angry>I'm in a bad mood, get out of here!");
-```
-The `~chatnpc` procedure causes an NPC dialog to appear in the player's chatbox. We have called this procedure as part of an `opnpc1` trigger, so `~chatnpc` will run when operation 1 (`Talk-to`) is triggered on the `border_guard_lumby` NPC.
-The result looks like:
-<nowiki>![image](https://github.com/user-attachments/assets/c288db66-8ae9-4c7d-a660-47183dfecc91</nowiki>)
-The important thing to know about procedures is that they **continue execution** of your script after they finish running.
-`~chatplayer` in particular will block execution until "Click here to continue" is clicked. Execution of your script will then continue from where it left off. This allows a scriptwriter to trigger additional actions during/after NPC dialogue, for example.
-==== Commands ====
-Commands are provided directly by the game engine and tend to be simpler than procedures.
-No special prefix is required when calling commands. For example:
-```ts
-[opnpc1,border_guard_lumby]
-mes("The guard, evidently in a bad mood, shouts at you to leave.");
-```
-The `mes` command prints a message to the player's chatbox.
-<nowiki>![image](https://github.com/user-attachments/assets/bae32d71-189f-4e96-b0be-e276d5dd05f4</nowiki>)
-==== Labels ====
-Labels are similar to procedures with one important difference: they '''halt execution''' of the calling trigger after they finish running.
-By calling a label, your trigger relinquishes control of the player. Execution of your script will not continue where it left off. Instead, execution begins at the label, and ends when the label ends, without returning to your trigger.
-Labels are mostly useful for chaining well-organized blocks of code together, using a trigger only as the initial entry point.
-You will often see a trigger call a label, which calls a second label, ... and so on.
-=== Packaging ===
-<blockquote>More in-depth on the server's directory structure. Now that the reader might possibly be capable of writing some RuneScript triggers, have them create a new .rs2 file in an appropriate location and add a test interaction.</blockquote>
-=== Configurations ===
-<blockquote>Zoom out from RuneScript and touch on configs, explain how they might add/change configurations for NPCs and locs, how to move a npc/loc/obj/seq from the `all.*` files into more appropriate locations</blockquote>