Mission Scripting: Difference between revisions

From Off Grid Wiki
Jump to navigation Jump to search
(Add MissionObject values as a test for adding tables)
 
(Start documenting mission scripting)
Line 1: Line 1:
== 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 [http://www.moonsharp.org 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 [https://en.wikipedia.org/wiki/Integrated_development_environment IDE], we recommend the following:
{| class="wikitable"
{| class="wikitable"
| '''Value'''  
|-
| '''Notes'''
| [https://atom.io/ Atom] || [https://github.com/atom/atom Open source] text editor with Lua extensions available
|-
| [https://code.visualstudio.com Visual Studio Code] || Closed source editor from Microsoft with Lua extensions available
|}
 
=== 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 ===
<syntaxhighlight source lang="lua" line>
mission = {
 
-- Mission info
startTime = {2009, 04, 27, 21, 13, 00},
 
</syntaxhighlight>
 
In this first code block we create the ''mission'' Lua table and define its first value.
 
{| class="wikitable"
! 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.
 
=== Characters ===
 
<syntaxhighlight source lang="lua" line start=5>
-- Character definitions:
characters = {
joe = {
displayName = "Joe Harman",
internalName = "Joe",
characterType = "player",
prefab = "player",
spawnpoint = "PlayerSpawn",
},
},
</syntaxhighlight>
 
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!
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:
{| class="wikitable"
!colspan="2" | 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!)
|-
| ''characterType'' || The 'type' of the character, see [[Character Types and Prefabs]] for more information on possible values
|-
| 'prefab' || The prefab for the character, see [[Character Types and Prefabs]] for more information on possible values
|-
| ''spawnpoint'' || The name of the spawn mission object, the position of this object will be where the character is spawned
|}
 
The ''characters'' table can hold information on as many characters as you'd like to fill the mission with, they won't be spawned into the mission until you decide (more on that later)
 
=== Physical Items ===
 
<syntaxhighlight source lang="lua" line start=15>
-- Inventory items:
items = {
usbkey = {
InternalName = "USBDongle",
DisplayName = "USB dongle",
Description = "Modified USB Bluetooth dongle given to you by the hackers",
UISpriteName = "usbdongle.png",
},
},
</syntaxhighlight>
 
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
{| class="wikitable"
!colspan="2" | 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
|}
 
=== Data ===
 
<syntaxhighlight source lang="lua" line start=24>
--[[ Data files:
Available data types: generic, text, SMS, encrypted, audio, video, location, key, UUID
]]--
data = {
PlayerPGPKey = {
internalName = "PlayerPGPKey",
name = "Personal PGP encryption key",
immutable = true,
dataType = 7,
creatorName = "Player",
dataString = "PGP Fingerprint: 1d7d ef54 7a63 5756 63a7 cf14 fbd8 775c c39d 4e51",
description = "AES 256-bit",
dataColor = {0.0, 0.6, 1.0, 0.3},
},
},
</syntaxhighlight>
 
The data table contains data that's specific to your mission, in this example we're defining the players [https://en.wikipedia.org/wiki/Pretty_Good_Privacy PGP] encryption key
 
{| class="wikitable"
!colspan="2"| Data Table
|-   
! Name !! Description
|-
| ''internalName'' || The internalName we'll use to identify this data (Must be unique!)
|-
| ''name'' || The display name of the data, this is what will be displayed in the games UI
|-
| ''immutable'' || Is the data immutable? If true the player won't be able to delete it, this is useful for data items that are part of mission objectives
|-
| ''dataType'' || The type of the data, this is used for displaying the data correctly
|-
| ''creatorName'' || The name of the data's creator (displayed in the UI)
|-
| ''dataString'' || The contents of the data file
|-
| ''description'' || A description of the data file
|-
| ''dataColor'' || RGBA value that's used as the colour of the data point when visible in the players data view
|}
 
=== Networks ===
 
<syntaxhighlight source lang="lua" line start=40>
-- Networks:
--[[ types: 0 = mobile, 1 = WiFi, 2 = mesh ]]--
networks = {
Semaeopus4G = {
name = "Semaeopus4G",
networkType = 0,
allowPlayerDisconnect = false,
userAccessKey = "user",
adminAccessKey = "admin",
rootAccessKey = "root",
},
},
</syntaxhighlight>
 
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
{| class="wikitable"
!colspan="2" | 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 ===
 
<syntaxhighlight source lang="lua" line start=52>
-- Mission objectives:
objectives = {
enterTheBuilding = {
name = "Enter the building",
onStart = function()
print("Player must now enter the building")
end,
onCompleted = function()
print("The player is now in the building!")
end,
},
},
</syntaxhighlight>
 
The objectives table contains all the tasks that the player should complete before your mission is finished.
 
{| class="wikitable"
!colspan="2" | Objective Table
|- 
! Name !! Description
|-
| ''name'' || The name of the objective (should be unique)
|-
| ''onStart'' || A callback function that's triggered when the objective is started
|-
| ''onCompleted'' || A callback function that's triggered when the objective is completed
|}
 
=== Checkpoints ===
'''TO DO'''
<syntaxhighlight source lang="lua" line start=64>
checkpoints = {
},
</syntaxhighlight>
 
=== Devices ===
'''TO DO'''
<syntaxhighlight source lang="lua" line start=66>
devices = {
laptop = {
internalName = "laptop",
script = "Scripts/Devices/laptop.lua",
},
},
</syntaxhighlight>
 
{| class="wikitable"
!colspan="2" | Device Table
|- 
! Name !! Description
|-
| ''internalName'' || The name of the device (Must be unique!)
|-
| ''script'' || The script that defines the gui and the behaviour of the device
|}
 
 
== API TEST (IGNORE) ==
{| class="mw-collapsible mw-collapsed wikitable sortable"
|-
! Value !! Notes
|-
|-
| name         
| name         

Revision as of 19:31, 5 May 2017

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 following:

Atom Open source text editor with Lua extensions available
Visual Studio Code Closed source editor from Microsoft with Lua extensions available

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

mission = {

-- Mission info
	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.

Characters

-- Character definitions:
	characters = {
		joe = {
			displayName = "Joe Harman",
			internalName = "Joe",
			characterType = "player",
			prefab = "player",
			spawnpoint = "PlayerSpawn",
		},
	},

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! 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!)
characterType The 'type' of the character, see Character Types and Prefabs for more information on possible values
'prefab' The prefab for the character, see Character Types and Prefabs for more information on possible values
spawnpoint The name of the spawn mission object, the position of this object will be where the character is spawned

The characters table can hold information on as many characters as you'd like to fill the mission with, they won't be spawned into the mission until you decide (more on that later)

Physical Items

-- Inventory items:
	items = {
		usbkey = {
			InternalName = "USBDongle",
			DisplayName = "USB dongle",
			Description = "Modified USB Bluetooth dongle given to you by the hackers",
			UISpriteName = "usbdongle.png",
		},
	},

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

Data

--[[ Data files:
Available data types: generic, text, SMS, encrypted, audio, video, location, key, UUID
]]--
	data = {
		PlayerPGPKey = {
			internalName = "PlayerPGPKey",
			name = "Personal PGP encryption key",
			immutable = true,
			dataType = 7,
			creatorName = "Player",
			dataString = "PGP Fingerprint: 1d7d ef54 7a63 5756 63a7 cf14 fbd8 775c c39d 4e51",
			description = "AES 256-bit",
			dataColor = {0.0, 0.6, 1.0, 0.3},
		},
		
	},

The data table contains data that's specific to your mission, in this example we're defining the players PGP encryption key

Data Table
Name Description
internalName The internalName we'll use to identify this data (Must be unique!)
name The display name of the data, this is what will be displayed in the games UI
immutable Is the data immutable? If true the player won't be able to delete it, this is useful for data items that are part of mission objectives
dataType The type of the data, this is used for displaying the data correctly
creatorName The name of the data's creator (displayed in the UI)
dataString The contents of the data file
description A description of the data file
dataColor RGBA value that's used as the colour of the data point when visible in the players data view

Networks

-- Networks:
--[[ types: 0 = mobile, 1 = WiFi, 2 = mesh ]]--
	networks = {
		Semaeopus4G = {
			name = "Semaeopus4G",
			networkType = 0,
			allowPlayerDisconnect = false,
			userAccessKey = "user",
			adminAccessKey = "admin",
			rootAccessKey = "root",
		},
	},

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

-- Mission objectives:
	objectives = {
		enterTheBuilding = {
			name = "Enter the building",
			onStart = function()
				print("Player must now enter the building")
			end,
			onCompleted = function()
				print("The player is now in the building!")
			end,
		},
	},

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

Objective Table
Name Description
name The name of the objective (should be unique)
onStart A callback function that's triggered when the objective is started
onCompleted A callback function that's triggered when the objective is completed

Checkpoints

TO DO

checkpoints = {
	},

Devices

TO DO

devices = {
		laptop = {
			internalName = "laptop",
			script = "Scripts/Devices/laptop.lua",
		},
	},
Device Table
Name Description
internalName The name of the device (Must be unique!)
script The script that defines the gui and the behaviour of the device


API TEST (IGNORE)

Value Notes
name The name of the MissionObject (readonly)
type The type of the MissionObject (readonly)
triggered Has the MissionObject been triggered (readonly)
position The (x, y, z) position values of the MissionObject (read-write)
rotation The (x, y, z) euler angles of the MissionObject (read-write)
isActive Is the MissionObject added? (read-write)
isMoving Is the MissionObject moving? (readonly)
OnTriggerEnter The lua callback for when the trigger volume is entered (read-write)
OnTriggerExit The lua callback for when the trigger volume is exited (read-write)
OnPreInteract The lua callback for pre interactions, returning false from this will cancel the interaction (read-write)
OnStartInteracting The lua callback for when the MissionObject starts being interacted with (read-write)
OnStopInteracting The lua callback for when the MissionObject stops being interacted with (read-write)
SlerpToObject(MissionObject target, float time) Slerps to the position and rotation of another object in 'time' seconds
SlerpToPos(MissionObject target, float time, bool inWorldSpace) Slerps to a position in 'time' seconds (can be in world space or local space)
LerpToObject(MissionObject target, float time) Lerps to the position and rotation of another object in 'time' seconds
LerpToPos(MissionObject target, float time, bool inWorldSpace) Lerps to a position in 'time' seconds (can be in world space or local space)