Missions and the mission list - Revision history

Zonkmachine: /* The player's mission list */ fixup

2025-11-09T22:34:34Z

‎The player's mission list: fixup

Zonkmachine: /* Registering a mission type */

2025-04-30T22:38:03Z

‎Registering a mission type

Zonkmachine: /* The player's mission list */ I -> We

2025-04-30T07:08:12Z

‎The player's mission list: I -> We

Zonkmachine: /* Mission description */ Fixup

2025-01-16T06:47:50Z

‎Mission description: Fixup

Zonkmachine: No longer outdated

2025-01-16T06:40:19Z

No longer outdated

Zonkmachine: /* Mission description */ Completed example

2025-01-16T06:38:28Z

‎Mission description: Completed example

Zonkmachine: /* Registering a mission type */ Fixup example

2025-01-16T06:28:57Z

‎Registering a mission type: Fixup example

Zonkmachine: /* Registering a mission type */ fixup - escape apostrophe

2025-01-16T05:54:03Z

‎Registering a mission type: fixup - escape apostrophe

Zonkmachine: /* Mission description */ Fixup - Taxi example

2025-01-16T05:41:53Z

‎Mission description: Fixup - Taxi example

Zonkmachine: /* Mission description */ Minimal buildMissionDescription fixup

2025-01-16T05:39:01Z

‎Mission description: Minimal buildMissionDescription fixup

@@ Line 1: / Line 1: @@
 ==The player's mission list==
-Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking at the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].
+Once the player has negotiated with your form, there might well be a mission in play. It could be a delivery, an assassination, a rush to tell somebody not to leave because so-and-so loves them... the possibilities are limited only by your creativity. The player needs a way to keep track of all the missions that they have agreed to undertake. Pioneer provides this through the player's mission screen, which they can access at any time using the F3 button, and looking under the missions tab. The content of this screen is controlled by some methods on the <code>Player</code> object, which can always be found at <code>Game.player</code>, and which inherits from <code>Ship</code> and <code>Body</code>. Missions are added to the screen using the <code>Mission.New()</code> method. It takes a table of info, and returns an integer reference to that mission, which should be stored so that it can be updated or removed later. Below follows a typical use case from the [https://codedoc.pioneerspacesim.net/#LuaClass:Mission:New codedoc].
 Create a new mission and add it to the player’s mission list while retrieving the reference number:

← Older revision		Revision as of 22:38, 30 April 2025
Line 62:		Line 62:


−	The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission ~~type~~ you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.	+	The next example is extended with a much scaled-down version of the '''[https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L401-https://github.com/pioneerspacesim/pioneer/blob/646f13acb76ab6ff3e407258c598e9e4012f5008/data/modules/DeliverPackage/DeliverPackage.lua#L434 onShipDocked]''' function from the '''DeliverPackage''' module. Since these missions are recognized by a module in Pioneer already ('Taxi') they will 'probably' be handled at a later stage if we fail to remove them with this test mission. If you generate a new mission you must also handle removing it or the mission will remain in the game forever. There is no automatic logic, and no automatic removal. Your script must keep track of them. We'll wrap the action in a '''Timer''' function so we don't have to deal with the BBS form this time.

	Timer:CallAt(Game.time + 2, function ()		Timer:CallAt(Game.time + 2, function ()

@@ Line 39: / Line 39: @@
   Event.Register("onShipDocked", onShipDocked)
-I don't recommend using <code>Game.player.frameBody.path</code> here. I'm only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.
+We don't recommend using <code>Game.player.frameBody.path</code> here. We're only using it because it always returns something, whether docked or not. A real mission would probably use a space station here. For this demonstration we've generated 'Taxi' missions that are already a known mission type, registered by '''Taxi.lua''' who wouldn't know about it because the mission scripts remembers it's own missions and has no way of knowing about missions registered by another module. So far no modules use another modules mission type and we only use it here for the sake of demonstration.
 This creates a mission visible on the mission screen:

@@ Line 157: / Line 157: @@
       return desc;
   end
 Let's fixup the earlier example with it's own mission type and a working '''buildMissionDescription'''.
@@ Line 226: / Line 224: @@
   Mission.RegisterType('Test', 'Test', buildMissionDescription)
   Event.Register("onGameStart", onGameStart)
 That's basically it. Here follows a description of the elements you can add to '''buildMissionDescription'''. Try and expand our latest script on you own.

← Older revision		Revision as of 06:40, 16 January 2025
Line 1:		Line 1:
−	~~{{outdated}}~~
−
	==The player's mission list==		==The player's mission list==

← Older revision		Revision as of 06:38, 16 January 2025
Line 161:		Line 161:

	[[File:Minimaldescription.png\|1024px]]		[[File:Minimaldescription.png\|1024px]]
		+
		+	Let's fixup the earlier example with it's own mission type and a working '''buildMissionDescription'''.
		+
		+	local Character = require 'Character'
		+	local Comms = require 'Comms'
		+	local Event = require 'Event'
		+	local Game = require 'Game'
		+	local Mission = require 'Mission'
		+	local Player = require 'Player'
		+	local Timer = require 'Timer'
		+
		+	local missions = {}
		+
		+	local onGameStart = function ()
		+	Timer:CallAt(Game.time + 2, function ()
		+
		+	-- On docking, starting a new game, we create
		+	-- two npc's and book them on a taxi mission.
		+	table.insert(missions, Mission.New({
		+	type = "Test",
		+	client = Character.New(),
		+	due = Game.time + 10, -- ten seconds
		+	reward = 10,
		+	location = Game.player.frameBody.path, -- here, basically
		+	status = 'ACTIVE'
		+	}))
		+	table.insert(missions, Mission.New({
		+	type = "Test",
		+	client = Character.New(),
		+	due = Game.time + 20, -- 20 seconds
		+	reward = 5000,
		+	location = Game.player.frameBody.path, -- here, basically
		+	status = 'ACTIVE'
		+	}))
		+
		+	-- Magically, without moving, we've arrived at the destination
		+	-- after 15 seconds and check in with our passengers.
		+	Timer:CallAt(Game.time+15, function () -- 15 seconds timer
		+	for ref,mission in pairs(missions) do
		+	if Game.time > mission.due then
		+	mission.status = 'FAILED'
		+	Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
		+	else
		+	Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
		+	mission.status = "COMPLETED"
		+	Game.player:AddMoney(mission.reward)
		+	end
		+	mission:Remove()
		+	missions[ref] = nil
		+	end
		+	end)
		+	end)
		+	end
		+
		+	local buildMissionDescription = function (mission)
		+	local ui = require 'pigui'
		+	local desc = {}
		+
		+	desc.description = ""
		+	desc.client = mission.client
		+	desc.details = {false}
		+
		+	return desc;
		+	end
		+
		+	Mission.RegisterType('Test', 'Test', buildMissionDescription)
		+	Event.Register("onGameStart", onGameStart)
		+
		+	That's basically it. Here follows a description of the elements you can add to '''buildMissionDescription'''. Try and expand our latest script on you own.

	===desc.description===		===desc.description===

@@ Line 71: / Line 71: @@
 Start the game and have a look under the '''Missions''' tab. After 2 seconds two missions are registered. One that should be finished in 10 seconds and another with a due time set 10 seconds after the first one. There is a second timer that checks in with the missions to see how it's going after 15 seconds. One should be completed successfully and the other will fail.
   local Character = require 'Character'
   local Comms = require 'Comms'
@@ Line 82: / Line 81: @@
   local missions = {}
-  local onShipDocked = function (ship, station)
+  local onGameStart = function (ship, station)
-      if ship:IsPlayer() then
+      Timer:CallAt(Game.time + 2, function ()
-     -- On docking, starting a new game, we create
+         -- On docking, starting a new game, we create
-     -- two npc's and book them on a taxi mission.
+         -- two npc's and book them on a taxi mission.
           table.insert(missions, Mission.New({
               type = "Taxi",
@@ Line 100: / Line 99: @@
               due = Game.time + 20, -- 20 seconds
               reward = 5000,
               location = Game.player.frameBody.path, -- here, basically
               status = 'ACTIVE'
           }))
-     -- Magically, without moving, we've arrived at the destination
+         -- Magically, without moving, we've arrived at the destination
-     -- after 15 seconds and check in with our passengers.
+         -- after 15 seconds and check in with our passengers.
-     Timer:CallAt(Game.time + 15, function ()  -- 15 seconds timer
+         Timer:CallAt(Game.time+15, function ()  -- 15 seconds timer
-         for ref,mission in pairs(missions) do
+             for ref,mission in pairs(missions) do
-             if Game.time > mission.due then
+                 if Game.time > mission.due then
-                 mission.status = 'FAILED'
+                     mission.status = 'FAILED'
-                 Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
+                     Comms.ImportantMessage('We are five seconds late and I\'m at a loss of words. I had been looking forward to this ride and now my day is simply destroyed!', mission.client.name)
-             else
+                 else
-                 Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
+                     Comms.ImportantMessage('Thanks for the ride!', mission.client.name)
-                 mission.status = "COMPLETED"
+                     mission.status = "COMPLETED"
-                 Game.player:AddMoney(mission.reward)
+                     Game.player:AddMoney(mission.reward)
               end
-             mission:Remove()
+          end)
       end)
   end
-  Event.Register("onShipDocked", onShipDocked)
+  Event.Register("onGameStart", onGameStart)
 Missions Created:

@@ Line 138: / Line 138: @@
 If you don't include the '''buildMissionDescription''' argument when you register the mission type, the mission list will not include a '''More info...''' button for the mission type. In the example above we used an existing mission type, '''Taxi''', but we didn't do it from within '''Taxi.lua''' so when '''More info...''' is pressed '''buildMissionDescription''' will be called in '''Taxi.lua''' but it will not now anything about the mission so the function will break. Try and comment out the entire '''buildMissionDescription''' in '''Taxi.lua''' and launch Pioneer once more. The Missions will register but now without the '''More info...''' button. To register a mission type without '''buildMissionDescription''' you simply leave it out.
-  Mission.RegisterType('Delivery', l.DELIVERY)
+  Mission.RegisterType('Taxi', l.TAXI)
 You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.
@@ Line 145: / Line 145: @@
   end
-  Mission.RegisterType('Delivery', l.DELIVERY, buildMissionDescription)
+  Mission.RegisterType('Taxi', l.TAXI, buildMissionDescription)
 The function responsible for interpreting the mission description is '''[https://github.com/pioneerspacesim/pioneer/blob/8a84b93e361d462baf6e0fc688679c0bc1ba7078/data/pigui/modules/info-view/04-missions.lua#L42-L77 drawMissionDescription()]''' in '''/data/pigui/modules/info-view/04-missions.lua'''. It takes a table '''desc''' as it's argument. A minimal working mission description could look something like the example below. We set '''desc.description''' to an empty string and '''desc.details''' to a table with only one element '''false'''. '''desc.client''' is set to '''mission.client'''. This only works as part of an actual mission script where you already have a registered mission with a client. As you can see the '''Mission Details''' title and the '''Go back''' button are generated automatically.

@@ Line 140: / Line 140: @@
   Mission.RegisterType('Delivery', l.DELIVERY)
-You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will launch a minimal info window with just the basics. A title, The customer image, and a '''Go back''' button.
+You can also declare a minimal '''buildMissionDescription''' that returns nil. This is fine. It will include the button which, if pressed, will just exit immediately and not try and open a new window.
   local buildMissionDescription = function (mission)