Intro

This article will describe everything you need to know in order to understand how to write and modify missions scripts in Off Grid!
Mission scripts can get a little bit large but don't let that overwhelm you, they're deceptively simple, we promise!

Pre-requisites

All modding scripts for Off Grid are written in Lua, it's a lovely little language which is simple ( don't tell it I said that ) and extensible thanks to the marvellous MoonSharp.

Lua is quite easy to pick up, even people with no programming experience should be able to get hacking in next to no time!

You'll need the following tools for editing and writing new mission scripts:

IDE

Firstly you'll need an IDE, we recommend the Atom with the following extensions:

Auto-complete support for Lua, we recommend enabling the "Override lower priority providers" in the plugin settings

You might also want to get our Atom Snippets code and copy&paste it into Atom's Snippets file to add nice autocompletion for Off Grid API.

LevelKit & Game

Both of these are needed in order to run and test and scripts you create

TO DO

The Mission Script Structure

As mentioned above, mission scripts can get rather large so this article will attempt to break down all the little sub elements, it can be helpful to try and think of the mission script in the same way you might think of a film script.
The vast majority of the script is simply defining what is in the world of the mission you've created.
Enough talking, lets jump into an example! Rather than posting an entire example script, we'll go from top to bottom exploring what each element does.

Initial Mission State

1 mission={2 3 -- Mission info4 startTime={2009,04,27,21,13,00},

In this first code block we create the mission Lua table and define its first value.

Name

Description

startTime

The start time of the mission in the game world (Year, Month, Day, Hour, Mins, Secs)

startTime doesn't have to be the current date, you can set your mission in any time you desire.

State

State includes anything you'd like to be saved & loaded. So for instance, you might want to set a bool on the first time a player enters a building, or performs an action, or completes a particular objective. Currently we only support numbers, bools and strings, and these need to have string keys (rather than indices).

Characters

This is the first example of us creating a sub table in the mission table, the characters table contains all the information about the characters in your mission! Different types of characters might need different values, and there are some optional settings as well for different purposes. Different character types and creating background profiles for the characters is explained in more detail in Character Profiles.

In this example we've added Joe, the protagonist of Off Grid. Here's a break down of what the value of Joe's table means:

Character Table

Name

Description

displayName

The name that will be used any game UI referencing the character

internalName

The internalName can be thought of as the id for the character, you'll reference the character by this value in a few places including conversations (Must be unique!)

The items table contains information about physical items that the player will be able to add to their inventory over the course of the mission, in this example we're marking up a USB dongle that the player can plug into computers

Item Table

Name

Description

internalName

The internalName we'll use to identify this item (Must be unique!)

displayName

The display name of the item, this is what will be displayed in the games UI

description

The description of the item, this will be displayed to users in the players inventory UI

uiSpriteName

The path to the items sprite, this is the image that will be used in the games UI

The networks table contains all the information about the possible networks in your game, networks can be of different types such as mobile networks, WiFi, and mesh

Network Table

Name

Description

name

The name of the network (Must be unique!)

networkType

The type of the network (mobile - 0, WiFi - 1, mesh - 2)

allowPlayerDisconnect

Is the player allowed to disconnect from the network?

userAccessKey

The password for user access to the network

adminAccessKey

The password for admin access to the network

rootAccessKey

The password for root access to the network

Data sent at higher access levels across a network won't be visible to devices that are connected at a lower access level.

Objectives

52 -- Mission objectives:53 objectives={54 enterTheBuilding={55 name="Enter the building",56 onStart=function()57 print("Player must now enter the building")58 end,59 onCompleted=function()60 print("The player is now in the building!")61 end,62 },63 },

The objectives table contains all the tasks that the player should complete before your mission is finished.

Devices

The name of the device. Must be unique and match the MissionObject in the scene

owner

Optional. The internalName of the device's owner. Use this if you want too restrict device's access base don owner's metadata or something.

script

The script that defines the gui and the behaviour of the device ( See device scripts for more information )

Mission Setup

73 functionSetupMission()74 -- add player and guards:75 Mission.AddCharacter(mission.characters.joe)76 -- these two below add in the guards which you might not have created yet!77 Mission.AddCharacter(mission.characters.jack)78 Mission.AddCharacter(mission.characters.john)79 80 -- set up hackable devices81 Mission.AddHackableDevice(mission.devices.laptop)82 83 -- set up networks:84 Mission.AddNetwork(mission.networks.Semaeopus4G)85 Mission.ConnectToNetwork(mission.devices.laptop,mission.networks.Semaeopus4G.name,mission.networks.Semaeopus4G.userAccessKey)86 Doors.SetNetwork(mission.networks.Semaeopus4G)87 Doors.SetZoneKeys("admin",{"adminkey"})88 89 -- misc.90 -- Player.SetInvisible(true)91 92 Mission.MissionStarted()93 end

This will add in all of your created elements into your level, below you will see what the function of each part of this code will do.

Adding in Characters

74 -- add player and guards:75 Mission.AddCharacter(mission.characters.joe)76 -- these two below add in the guards which you might not have created yet!77 Mission.AddCharacter(mission.characters.jack)78 Mission.AddCharacter(mission.characters.john)

This part of the code shows the format of adding in characters - this includes the player and any NPCs like the guards, which you will have created further up in your Mission Script. If the title of your character table for your player was called jenson, you would simply change Mission.AddCharacter(mission.characters.joe) to Mission.AddCharacter(mission.characters.jenson), this would now let your player spawn in.

Adding in Hackable Devices

Once you have set up some hackable devices, by adding this to your SetupMission() the hackable devices will now be added into your level. Similarly to adding in the characters as seen above, to customise this for your own devices, you only need to change the last part inside the brackets. So if the title of one of your devices tables was vendingmachine, you could just change Mission.AddHackableDevice(mission.devices.laptop) to Mission.AddHackableDevice(mission.devices.vendingmachine).

You will have already created a network in your networks table. Now to add it into the game you need to just add in Mission.AddNetwork(mission.networks.NETWORKNAME) where NETWORKNAME is the title of the table you created in your networks table, in this tutorial it was defined as Semaeopus4G. To then connect your hackable devices to your network you just need to add in what you see on line 86, where laptop can be replaced with the hackable devices table name, though in our example the table of our hackable device is called laptop, so we'll keep it as it is.

Once you have created doors you can then also add them to a network. By adding them to a network you can make it so that the player cannot open the door unless they have a key. Firstly you add the door to a network, then you can set the door's zone to require a specific key to open it. In our example where we set the zone's required key: Doors.SetZoneKeys("admin", {"adminkey"}), "admin" is the name of the zone the door is assigned to, and "adminkey" is the name of the key that will allow the player to unlock the doors of the zone "admin".

Adding in Other Changes

89 -- misc.90 -- Player.SetInvisible(true)

Whilst modding you might get to a point in development where you need to test features like the patrol routes of guards, so a useful line of code you can add to your MissionSetup() is Player.SetInvisible(true), this will make your player invisible to the Guards which can certainly be handy for testing your level without being spotted!

Including other files

We know how long these mission scripts can become. As a result, we came up with a method of splitting up your mission into smaller, bite-size pieces. You're more than welcome to keep your mission in a single file, but if you want to manage them differently, read on...

Let's say you want to keep all your device related shenanigans in a separate file for clarity. We could call this 'mission_devices.lua', and put it in the same folder as the mission. We still need a table of devices, but we also need a function to return it.

The key bit here is that the devices table is now defined to be the table returned by the function we wrote in mission_devices.lua. If we took this to its natural conclusion, we end up with the following: