The Quest System

Weird Worlds mod tutorial: The Quest System

Last updated 11/26/2006

This will hopefully become a comprehensive manual for using the quest system in Weird Worlds. In the first edition I'll attempt to simply write a reference manual that covers each command that is used in quest files (.ini files found in gamedata/quests/) and tells you what it does. The subject is rather complex so this tutorial may grow over time with things like practical examples being added.

Table of Contents

1. What is a Quest
2. Command Reference
3. Glossary

1. What is a Quest

The name Quest system is somewhat misleading, as the system ended up being used for a lot of scripting that has nothing to do with "quests" (as in "missions"). However, that's what the thing's called in code and filenames so we're calling it that here...

To put it simply, the Weird Worlds Quest System is a text-based file format that allows you to make simple scripts to display text and images, as well as affect the gameplay in a variety of ways. You can use it to set up conditions that trigger an event, or different events depending on player actions. Even simple "programming" and communication between different quests is possible with user-defined variables. All quests are .ini files located in gamedata/quests under the default or a mod folder.

Writing a complete tutorial to teach you the ins and outs of quest-crafting is outside the scope of this document (at least for now). The recommended ways to learn are studying and imitating the existing quest files, and asking questions at the ISF Forums "Mod Surgery" section. Many veteran modders hang out there, and I stop by from time to time myself.

A few examples of quest files and what they do:

colony.ini
Creates a forest planet at a random star system and places a "Calatian Colony" event there along with an ambassador whom you can take with you.

crysfish.ini
A quest where having the right item with you changes the outcome of an encounter with a hostile alien race.

ripcord.ini, farseeker.ini, kuti.ini
Quest files that place a Terran ship, Muktian ally and a Zorg mercenary on a random planet in the sector.

gameover.ini, game_brass.ini, tutorial.ini
"Utility files" that contain various gameplay related text messages.

2. Command Reference

This is a list of all the commands used in quest files and their parameters. It will be updated with each new release of Weird Worlds if there are any changes.

Main quest commands

Commands used outside of STAR, CONDITION and PAGE blocks (typically in the very beginning of the quest file).

FLAG <list of flags>
This is a "bitflag" that defines some properties of how and when the quest is activated. Multiple keywords can be written on this line if necessary. Legal flags include:
always - The quest is always activated at the beginning of game.
event - The quest may appear as a "random event". In each game, some number (e.g. 4 on the large map) of random events occur.
ally - This flag must be included if the quest can give you a new ally (ie. a starship). It makes sure you get no more than a set number of allies.
mainquest - This is an important quest. Only one mainquest may be active in each game, and only one game out of eight will activate a mainquest.
tutorial - The "quest" is used for tutorial messages. They will be displayed separately from other quest messages so they can work simultaneously.
gamemsg - The "quest" is used for miscellaneous game messages like when you run out of time.
never - The quest can only be activated by the mission settings. (e.g. the pirates and military use different quests for their game messages).

KEYS <list of keywords>
This is a list of keywords. How these work is, no two quests with the same keywords can be activated. If you want to create two or more mutually exclusive quests in a mod, simply come up with a (previously unused) keyword and put it on the KEYS line in each of your quest files. Up to eight keywords can be used per quest.

STAR <0-3>
Begins a STAR block (end with END STAR). See below for more.

CONDITION <0-9>
Begins a CONDITION block (end with END CONDITION). See below for more.

PAGE <0-9>
Begins a PAGE block (end with END PAGE). See below for more.

END This goes in the very end of the quest file.

Note that the numbers after STAR, PAGE and CONDITION must always be in order starting with zero as the first block of that type.

STAR block commands

Commands that are used between the STAR <n> and END STAR. The STAR block is used to "set up" a location to be used by the quest, which may involve creating new planets, placing items and alien fleets or initializing user variables.

FLAG <list of flags>
This is a bitflag that determines how the game picks a star system for the quest, and whether the star becomes protected from hostile attacks. Legal flags include:
protect - Turn on protection. No hostile aliens will travel to this star, nor can it be affected by the Aethric mirror.
nearby - Picks a star within 1/3 of the map width from where the player starts.
faraway - Picks a star further than 2/3 of the map width from the player.
offmap - Don't pick a star at all; if this STAR block defines a fleet it will be placed off the map.
existing - Picks a star system that already has a planet that matches the PLNT setting (below).

NOFL <list of flags>
Exclude any star systems with the listed flags. For example, "NOFL binary1 binary2" exludes all binary stars.

PLNC <planet class>
Define planet class. For instance, "PLNC desert" will create a planet whose CLAS in the planet file is set to "desert".

PLNT <planet type>
Define planet type. This is simply the filename of the planet in gamedata/planets. E.g. "PLNT hope". PLNN <planet name>
Names the planet orbiting the star. E.g. "PLNN Earth"

STRC <star class>
Define star class. For example, "STRC exotic" will create a random exotic star.

STRT <star type>
Define star type. Just like the planet type, only with stars.

STRN <star name>
Names the star. E.g. "STRN Sirius"

ITEM <item filename>
Create a specific item and place it in this star system. E.g. "ITEM ps_calamb"

FLET <race> <n> [attack <race>]
Create fleet N of the specified race. Optionally can be told to attack the homeworld of another race. E.g. "FLET garthan 9 attack terran".

HOME <race>
Make this star system the homeworld of the specified race. Should only be done with races who otherwise don't have a homeworld.

UVAR <variablename> <value>
Sets a variable to a new value. This is a good place to initialize all variables used by the quest. Otherwise a value could be left in memory from the previous game.

END STAR
Ends the STAR block and goes back to parsing main quest commands.

CONDITION block commands

Commands that are used between the CONDITION <n> and END CONDITION. The block is used to define a condition when a quest event may or may not occur. A condition consists of a type (what kind of event is being checked), and one or more parameters. The parameters may be numeric or a string of text. Numeric parameters are called PAR0-PAR3 and string parameters are STR0-STR3 (although the strings are sometimes used for numbers as well). The condition is either TRUE or FALSE at any point during the game. When all conditions listed in a quest PAGE block (see below) are TRUE, the other commands within the PAGE are executed.

TYPE <condition type>
Determines what kind of condition is being checked. Valid types include:
explore - TRUE when you arrive at the planet STR0 (STR0 must be a number between 0-3) for the first time.
firstenc - TRUE when you meet race STR0 for the first time (STR0 must be a race filename, e.g. garthan).
preenc - TRUE when you're entering orbit, just about to encounter race STR0 (checked before radar screen).
encounter - TRUE when you encounter a fleet or homeworld of race STR0.
homeworld - TRUE when you arrive at the homeworld of race STR0.
nothome - TRUE if you are NOT located at the homeworld of race STR0.
knowrace - TRUE if you have previously encountered race STR0.
haveshiprace - TRUE if you have an allied ship of race STR0.
isfriendly - TRUE if you are currently friendly with the race STR0.
notfriendly - TRUE if you are not friendly with the race STR0.
haveitem - TRUE if you have an item whose NAME or KEYS match STR0 (If TRUE, puts the name of the item in the variable "haveitem").
noitem - TRUE if you don't have an item whose NAME or KEYS match STR0 (If FALSE, puts the name of the item in the variable "haveitem").
nopayment - TRUE if you refuse to pay race STR0 for services in combat.
uvar - TRUE if user variable STR0 has value STR1.
fleetarrive - TRUE when the quest-defined fleet PAR0 (0-3) arrives at quest-defined STAR PAR1 (0-3). If PAR1 is set to -1 or undefined, this condition is TRUE whenever the fleet arrives at any star system.
fleetleave - TRUE when the quest-defined fleet PAR0 leaves the STAR PAR1. If PAR1 is -1 or undefined, TRUE whenever the fleet leaves a star system.
fleetdestroy - TRUE when the quest-defined fleet PAR0 is destroyed for any reason (player action, nova explosions or otherwise).
gameover - TRUE when the game ends. If PAR0 is defined (0-7), only TRUE if the reason for the end matches PAR0:
  0: Returned to homeworld successfully and on time.
  1: Returned to homeworld successfully but late.
  2: Became lost in space, or quit game.
  3: Destroyed in combat.
  4: Sucked into a black hole.
  5: Annihilated by a vacuum collapser event.
  6: Blown into bits by a nearby supernova.
  7: Player's homeworld was destroyed.
tutorial - TRUE when a new tutorial message is displayed. PAR0 (0-9) identifies the topic:
  0: Starmap screen.
  1: Homeworld trade.
  2: Trader homeworld trade (Klakar).
  3: Finding an item.
  4: Random events.
  5: Acquiring a new ally.
  6: Encountering unknown aliens (radar screen).
  7: Combat interface.
  8: One of your ships has been damaged.
  9: Setting up a formation.
gamemsg - TRUE when a game message or (non-tutorial) help screen is displayed. PAR0 (0-5) determines the message:
  0: Halfway point in your mission.
  1: Two years of mission time left.
  2: Out of mission time.
  3: Pop-up that explains you must select a flee destination.
  4: F1 help screen in starmap mode.
  5: F1 help screen in combat mode.

PAR0 <n>, PAR1 <n>, PAR2 <n>, PAR3 <n>
Sets one of the numeric parameters to <n>.

STR0 <string>, STR1 <string>, STR2 <string>, STR3 <string>
Sets one of the text string parameters to <string>.

END CONDITION
Ends the CONDITION block and goes back to parsing main quest commands.

PAGE block commands

Commands that are used between the PAGE <n> and END PAGE. These are the commands that directly make something happen, from playing a sound effect to giving you a brand new starship. A single PAGE block can also be called an "event".

REQ0 <n>, REQ1 <n>, REQ2 <n>, REQ3 <n>
Required conditions. All of these must be TRUE for the event to occur. Up to four conditions can be defined for each PAGE block, and several PAGE blocks may use the same conditions (although the GOTO command is preferred over fully identical condition sets).

DISP <n>
Optional command that will force the event popup to use its own window. Normally events output into the exploration window if triggered by exploring a star system, but setting DISP 1 overrides this behavior.

ACTN <list of actions>
A list of "flags" that determine how the PAGE will be handled.
popup - This must be set if you want to display text or images.
endquest - The quest is completed after this PAGE block. No other PAGEs will be checked.
break - Prevent further PAGEs from being evaluated during this event. Useful if you have overlapping conditions.
trade - If the event summons an alien flotilla, initiate trade.
combat - Immediately go into combat mode (never used in the default game, untested).
mercpay - If the event summons an alien flotilla into combat, require payment afterward.

GFXP <image file> [frame]
If popup action is set, display an image. If frame is undefined, uses the first frame. E.g. GFXP misc/events.jpg 12

TITL <title text>
Set the title for the popup window.

TEXT <text string>
Display a paragraph of text in the popup (or exploration) window. Note that this should be composed as maximum of 8 lines of 26 characters each. Do not use line breaks in the quest file as they won't work; instead mark line break locations with a <br> tag.

MUSC <music file>
Play music during the popup. Music must be a stereo .ogg file. E.g. MUSC music/victory.ogg

YSNO <yes page> <no page>
The popup presents a yes/no question and then goes to a different PAGE block depending on player's answer. DISP 1 must be used if this PAGE was triggered by exploration. Note that if one of the destination PAGEs is set to -1, selecting that option simply closes the popup.

GOTO <next page>
The popup switches to a different PAGE (number between 0-9) when you close this one. Useful for multi-page messages.

WISH <success page> <fail page>
The player is allowed to type in a wish for an item. Then goes to a new PAGE depending on success. A WISH may fail if player writes the name of an item that isn't known or otherwise cannot be wished for. The latter category includes items that are (for example) structural parts of spaceships so they couldn't be "installed", as well as unique artifacts if one already exists in the world.

BOMB <yes page> <no page> <size> <timer>
Set off a Limited Vacuum Collapser device, with a confirmation. Then goes to a new PAGE depending on player approval. The player is allowed to set the timer (and the last value on this line is ignored.. please set it to -1 in case this changes).

SOND <sound file>
Play a sound effect when the event occurs. Does NOT require popup window action.

REMV <item name>
Permanently remove an item from the player's cargo bay. The name must be an exact filename from gamedata/items/, e.g. REMV dv_collapser

ITMS <n> <item flags>
Create n (one or more) items at player's current location. The names of the created items are stored in variables newitem1, newitem2 and so on. The useful flags include: life tech loot unique

ITEM <item name>
Create a specific item and add to the player's cargo bay. This ALWAYS WORKS regardless of the restrictions (e.g. uniqueness) placed on the item in question.

SHIP <race> <ship number>
Add a free new ship to player flotilla. The race must be one of the race filenames in gamedata/races and the ship number is one of the ships within that file (first ship is 0). E.g. SHIP terran 4

ALLY <race> <ship number>
Add an ally ship to player flotilla. Works like the SHIP command, except used to keep "independent" allies separate from clearly player-owned ships.

MERC <race> <ship number>
Allow the player to hire a mercenary by giving him/her a useful item. The parameters work like with SHIP and ALLY. Should probably only be used within exploration-triggered PAGEs.

FRND <race>
Instantly befriend an alien race. No more combat against them will occur. The race must be one of the race filenames in gamedata/races.

ENMY <race>
Instantly make an enemy out of an alien race. Next time you encounter them, combat will occur.

SUMN <refuse page> <fail page> <race>
Attempt to summon an alien flotilla. If they refuse to arrive or cannot be contacted, goes to another PAGE.

FIRE <weapon item> <flags>
Cause a special weapon to fire. The weapon must be defined as an item in a file in gamedata/items and is referred to by its filename. The only valid flag is autotarget which selects the hostile ship with most hull points left. If this flag is not set, the weapon fires forward from player ship (untested).

TIME <days>
Wait for a number of days in game time.

TPOS <success page> <fail page>
Use the Aethric Mirror transpose effect and go to a new PAGE depending on the outcome. If the success or fail page is set to -1, no new PAGE is displayed.

THIF <success page> <fail page>
A thief attempts to steal something valuable from the cargo hold. If nothing can be stolen, goes to the failure page. Only works if triggered by exploration.

SABT <success page> <fail page>
A saboteur attempts to destroy player's ship systems. If nothing can be broken, goes to the failure page. Only works if triggered by exploration.

NOVA <star> <timer> <radius> <new star> <new planet>
Trigger a supernova explosion at one of the quest-specified STARs (0-3), after set number of days. Radius is given in lightyears. The star and planet type are changed in the event, typically to a neutron star and a devastated system.

SVAR <variable name> <value>
Set a user variable to a new value.

SCOR <value> <score class>
Give the player some points. For example, SCOR 200 exploring will result in 200 star bucks in the exploration score class (modified by the mission type). Valid score classes from distribution.ini: other, starships, exploring, strategic, lifeforms, artifacts, technology.

GOVT <long game over text>
Message that will be displayed in the game over screen. Usually a paragraph or two.

GOVR <short game over message>
End the game, and set the text that will be shown in the highscore list. E.g. GOVR Sucked into a black hole

GOVP <image file> [frame]
An image that will be displayed in the game over screen. Frame number is optional. E.g. GOVP misc/sucked.jpg

XPLR <star> <value>
Explore or "unexplore" (revert to unexplored) a star system defined in a STAR block. The value can be between 0-2:
0: Set a STAR unexplored.
1: If unexplored, set to "semi-explored", like a black hole when it's first found.
2: Set to fully explored.

UNPR <star>
"Unprotect" a star. You should generally do this once a "protected" star in the quest is no longer needed but the quest still remains active. For example, once the player gets Damocles (in damocles.ini), the star it was at becomes unprotected.

INIT <star>
Initialize a quest star system. This creates the items and fleets in the STAR entry and sets variables. May misbehave if it modifies an actual star system and the map is already explored (so a planet you've visited might be changed).

INCV <variable> <number>
Increments a user variable by an integer (or subtracts if the number is negative).

CHNG <star> <param> <value>
Change a star system's parameter to a new value. Only allows changing PLNT, PLNN, STRT, STRN.

ADDT <days>
Add a number of days to the game's deadline.

3. Glossary

Bitflag
A way to store "bits" of info. Used for various options that can only be turned on or off. In Weird World Quest System a bitflag line usually starts with the FLAG command followed by a list of properties you wish to turn on.

CONDITION block
Part of a quest file, which starts with a CONDITION command and ends with END CONDITION. Usually defines a condition used to trigger an event, or allow/disallow an event to be triggered. This may be used to check the values of variables, or whether the player has a certain item, or when he lands on a certain planet and so on.

Event
An event corresponds to a single PAGE block, ie. anything that occurs because of a specific set ot conditions. A quest will often have a number of events that are triggered by different player actions. A "random event" is a gameplay term which means a quest that is activated at random (For example, on a large map the game picks four random event quests).

PAGE block
Part of a quest file, which starts with a PAGE command and ends with END PAGE. Usually defines the outcomes of a single "event", as well as lists which conditions must be met in order for the event to occur. The PAGE block is where things actually happen, from playing a sound effect to giving you a new starship.

Quest file
An .ini file that is placed in gamedata/quests, and whose name is included in the QUESTS section of gamedata/game.ini.

STAR block
Part of a quest file, which starts with a STAR command and ends with END STAR. Usually defines a star system where some part of a quest occurs. In a boardgame sense, each STAR block is like a token placed in a space on the board. It may define a special enemy fleet or a strange event or an item that is placed in a star system, or just set up a variable.

User Variable
See Variable.

Variable
In the Weird Worlds Quest system a variable, or user variable is basically a way to store a string of text so that it can be accessed by different parts of the game. For instance, the names of your ship and captain are stored in such variables so that a quest may include them in a paragraph of text. The "contents" of a variable are referred to as its value.

[GO BACK]