How to customize Infomancer Forge's export for your game.

Infomancer Forge’s goals is to give any game developer an easy and informative place to design game data. So if you need monsters, dialog, cards, spells, loot, quests. Just about anything. Link them together visually and see how they related.

All of this is great but often your games have a specific data format for information. This tutorial is about how you can do that with Infomancer Forge.

We selected another project from the ToolJam3. The project in questions was ChoiceEngine. Choice Engine uses a text file for a game description and we decided it was a perfect example of how Infomancer Forge can be used to enhance projects.

This tutorial is also available on our web page, that version will be kept up to date if things change. You can see it here.

Structure

Choice engine creates a story through locations and choices you make at each. Additionally each location may have a zombie fight that is managed by the game engine. To build this in Infomancer we create three Gobs.

• ChoiceGame.
• Location.
• Option.

Choice Game

The Choice game was added to make it easier to figure out the starting Location of a story and to allow the capturing of multiple stories that may even share a lot of parts.

We have a name for what our story is. We also have a single GOB reference to a starting node. Later we will export each story into it’s own folder with a store.txt file in it. That story will be composed from this node.

Location

The location has a description a description, array of Options and if it is a combat or not.

Locations are named Base nodes. Notice that we make Options an array. This allows us to add more then one reference there.

Currently there is no way to force only a certain number of options. Like 2 as this game requires. This has been added to features a min and max number of links.

We captured all the locations from the story.txt file as you can see in the screen shot below.

What is important to notice here we did not capture the options. This is because as they are arrays or references it’s easier and more meaningful to capture those on a View. All the data could be captured in either place but views make links much easier to build.

Option

The Option has a text description and a single destination Gob back to location.

Of note here is that the Option GOB has been declared as Embedded. This means that it does not have a Name and would in normal situation be embedded into the Location. Here we choose to make it embedded because each choice does not need a unique ID so we are not asked to name each one as we create them.

View

Now that we have our basic GOB’s designed we can capture the adventure game. The image below is the fully captured and edited Sample adventure from the first release of Choice Engine.

You can see how the color choice helps us visualize the information. We did have to move things around a bit so we can easily see how all the pieces connect to each other.

If you look at the bottom right you will see two story nodes that were not included in the final story in the sample game. A view like this makes it very easy to identify that.

Exporting the Project

So now that we have an adventure captured we need to build the part that takes all that data and turns it into something our game can use. We created two new scripts choiceEngine.lua and choiceInit.lua both will be broken down in more detail below.

choiceInit.lua

Choice init is the script that adds the export to the menu and binds the module of choiceEngien.lua into the application.

local ui=require("ui")
local choice=require("choiceEngine")

ui.addMenuAction({
	actionId="project.choice.export",
	name="Export Choice Engine",
	path="Project",
	icon='iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAIOSURBVDhP1ZK7a1RREMa/795NTDDsoqyuEldR0sQFER/YKGLho/GBWqQLYqEgWKkgVpapIkFRQSxEfBAsIiSCxaKyhSAGLRTEwkSjYVNEMGY1m7338zsb8zeIc5jzmJnzmzlzL/65kMWoWyfT91gFoWFLBOKXHS/YoyE9xACe2rMXMRJ7Yu/t9L6BOCrzZoRlOIPlNsbWDFKvDWSboGuegRU+5722WkNMizVjxBIkasEpos/MHMSBiPi9EKizaTOQD3hMvep1+CFejRJ8Y4xWlxBA8wQKqVl5Zwjrek2rodPOnEMd/fjODsNOGDTvAWxQrJXpbXRgAjP44DsztrYRN/yeCBGH+EXDWmsjuIMfUWUXChrROdUxiyMGpdaa623DM/bjui6E2ChMf4XYyWx8mRnk+BxdGMUErzi78faOURh1VW/sH8N5buPWcCljKs32m8yu6EdS8f6O9vlc5D2W7EsDgI9IjnPWN6TVSvBJkwEQYwsuoR0xa+7FUXx2sSVDD/Itl6Lq8O2Y8+h2y6hN6V3t1jA69Rp73Ksy3hH7OYjDOo6iK6i5moyxPx3d57RZ3dJF5Q0IPUhcy+J/4E9lLWOQeOn8I3jF8ahkU3hx+JwZTGtS7VqHjXiMKR5gnQs/UpAASDymFIctuIv3WWWPMyRNNxGpoK+qaA038wnqBszZtwgI4r6p07343wX4A+LzvQlCDxQCAAAAAElFTkSuQmCC',
	adjustColors=true,
	action=function() 
		choice.exportGames() 
	end 
})

We add a single menu item into Project the icon is a base64 png of what we would like the menu item to look like. Once added we get the following new menu item.

When someone clicks that it will run the code in the function action points to.

choiceEngine.lua

This is where we take the gobs as a Lua table and rework them into the text file. There is some tricky recursive stuff needed here so we don’t add nodes that are orphaned.

local choiceEngine={}

local table=require("tables")
local json=require("json")

-- Adds a choice to a line will also add a location to the set if it's not know.
choiceEngine.addChoice=function(text,line,locationName,knownLocations,locations,option)
	option=option or {}
	return line .. "|" .. (option.description or 'Continue') .. "|" .. choiceEngine.addLocation(text,option.destination,knownLocations,locations)
end

-- Returns the number of the location
choiceEngine.addLocation=function(text,locationName,knownLocations,locations)
	-- Don't add a location we have already added
	if locationName~=nil then
		if knownLocations[locationName]==nil then
			local locationNumber=#text+1
			text[locationNumber]=""
			local l=locations[locationName]
			local line=l.description
			local o1,o2
			if l.options~=nil then
				o1=l.options[1]
				o2=l.options[2]
			end
			knownLocations[locationName]=locationNumber
			line=choiceEngine.addChoice(text,line,locationName,knownLocations,locations,o1)
			line=choiceEngine.addChoice(text,line,locationName,knownLocations,locations,o2)
			if l.combat then 
				line=line .. "|true"
			else
				line=line .. "|false"
			end
			text[locationNumber]=line
		end
		return knownLocations[locationName]
	end
	return 1
end
 
choiceEngine.exportGames=function()
	-- this is needed for now sine the GOBS type is not done in a ways the lua libraries understand
	local lua=table.tostring(gobs,"","","")
	local baseGobs=load("return " .. lua)()

	if baseGobs.ChoiceGame~=nil and baseGobs.ChoiceGame.data~=nil then
		local locations={}
		-- Create a named list of all locations
		for n,g in pairs(baseGobs.Location.data) do
			locations[g.name]=g
		end

		-- For each game perform export
		for n,g in pairs(baseGobs.ChoiceGame.data) do
			local gameText={}
			local knownLocations={}
			-- Add first location it will do the rest
			choiceEngine.addLocation(gameText,g.startLocation,knownLocations,locations)

			-- pack into a single text string
			local story=""
			for l,t in ipairs(gameText) do
				story=story .. t .. "\n"
			end

			-- Save the string to the file
			environment:saveFile("Build/" .. g.name .. "/story.txt",story)
			print("Story " .. g.name .. " saved to Build/" .. g.name .. "/story.txt")
		end
	else
		print("Unable to find games to export.")
	end
end

return choiceEngine

So its about 75 lines not really a huge piece of code. I could shorten it but I really wanted to keep it more readable.

It keeps track of each location it has added while adding it and this allows us to reference backwards to locations without adding them a second time. Adding the first location will then add each location those choices call and it will keep doing that until all locations needed have been added.

Final output file

Once we click the export button it will create a story folder in Build and write story.txt into it.

You are a survivor in a post-apocalyptic world infested with zombies. You have heard that there is a safe haven for survivors in a nearby city and you decide to undertake the perilous journey there. Your mission is to make wise decisions and ensure that you survive the dangers in the road and reach a safe place|Use the main road|2|Take the road less traveled|11|false
You go down the main road and you meet several zombies. What do you do?|fight zombies|3|run|10|false
You see a hospital in front of you, what do you do?|Go to the hospital|4|ignore hospital|7|true
You get a key from the monster|Continue your path|5|investigate the hospital|6|true
After several hours of walking, you finally arrive at a shelter where you are received and you live peacefully for the rest of your life.|YAY|1|YAY|1|false
you realize that the key is for a bunker under the hospital, where you find people and security|YAY|1|YAY|1|false
Injured and tired, you continue advancing on the highway, you find a person alive on the ground, he tells you that there is no shelter, everyone is infected|don't believe him|8|believe him|9|false
Congratulations, you have saved the camp, now you are a zombie, but everyone will remember you as a hero.|YAY|1|YAY|1|false
Now you are a zombie, thanks to the death, there is a camp with humans, so you eat them|YAY|1|YAY|1|false
You run away and the zombies chase you, but you manage to escape.|continue|11|continue|11|false
You come across a police barrier that covers the road, what do you do?|investigate restaurant to find a way to go around|12|jump the barrier|13|false
You find an energy drink and a door to the back, when you open the door a zombie appears|continue|6|continue|6|false
When you jump over the barrier, a zombie grabs your foot and bites you, you fall on the other side, you see some lights at the end of the street|go to abandoned ambulance|14|go towards the light|15|false
you find yourself with 3 bandages and a frenzy|continue|15|continue|15|false
The light you saw is a refuge, a base with survivors, they are being attacked by zombie|help them|8|do not help|9|false

Full Version

The full version of this project is downloadable from the version of this tutorial on our web.