Entity Tutorial 2: Simple Script

In this tutorial, we will upgrade the Shiny Gem object from Tutorial 1. Now instead of using a literal string for the description, the description will be generated by LUA code.

Generally, if only returning a static string, a string literal like in the previous tutorial should be used due to performance reasons. However, this will demonstrate the simplest possible LUA code before we expand upon it in the next tutorial.

Definition Upgrade

Now for description, we set the parameter programString to true, to indicate that there is a description() function in the lua code that can be called for the description. It is a 'string' because that is the return type of description(). Other parameters might be programBoolean, programVoid, etc. See the reference docs for the return type.

There is one other new parameter in the JSON, something called luac. That is the base64 version of the compiled lua program. Let's generate that in the next step.

{
	"type": "ENTITY",
	"name":
	{
		"literalString" : "Shinier Gem"
	},
	"description":
	{
		"programString": true
	},
	"luac": "???"
}

Writing the LUA code

We create a simple LUA program in a folder on our HDD and name it shinierGem.lua:

-- Description is called when an object's description is shown to the
-- player or otherwise requested.  The object should return a string
-- containing the description.

function description()

   -- Create a descriptive string
   local descriptiveText = "The gem shines programatically as you look at it.";

   -- Return it
   return descriptiveText;

end

What the game will do is see that description has a programString available, and when requesting description will call description() and use its return value for the description.

If we just try to run this code from the command line, it won't be overly interesting:

> lua shinierGem.lua                                                       

Nothing happens. This is because the game calls the description() function, whereas nothing is calling the description function for the command line version of lua. We could quickly hack this just for quick testing purposes by adding a call to description():

-- Description is called when an object's description is shown to the
-- player or otherwise requested.  The object should return a string
-- containing the description.

function description()

   -- Create a descriptive string
   local descriptiveText = "The gem shines programatically as you look at it.";

   -- Return it
   return descriptiveText;

end

-- NEW!  Output return value of description() for quick test:
io.write("Just for testing on the command line purposes, description returns: " .. description() .. "\n");

Note the last added line, this will now output to the console if we run the LUA through the command line.

> lua shinierGem.lua 
Just for testing on the command line purposes, description returns: The gem shines programatically as you look at it.

Running from the command line can be helpful for finding any LUA syntax or logic errors, if your program doesn't rely on any functions from the game. However, since the command line version of LUA doesn't know about any game logic, most advanced programs can't use this trick. Regardless, now that it's been tested, we should remove the debug statement and go back to our original program:

-- Description is called when an object's description is shown to the
-- player or otherwise requested.  The object should return a string
-- containing the description.

function description()

   -- Create a descriptive string
   local descriptiveText = "The gem shines programatically as you look at it.";

   -- Return it
   return descriptiveText;

end

Now, let's compile the program. We can use luac instead of lua to create lua bytecode instead of running the program.

> luac shinierGem.lua

There is now a luac.out file. If you open it in a text editor, it'll look like gibberish as it's a binary file. Since we need to put this luac into the JSON file from earlier, we'll use the base64 utility to convert the binary file into an ASCII representation.

> base64 luac.out
G0x1YVEAAQQEBAgAEAAAAEBzaGluaWVyR2VtLmx1YQAAAAAAAAAAAAAAAgIDAAAAJAAAAAcAAAAeAIAAAQAAAAQMAAAAZGVzY3JpcHRpb24AAQAAAAAAAAAFAAAADQAAAAAAAAIDAAAAAQAAAB4AAAEeAIAAAQAAAAQyAAAAVGhlIGdlbSBzaGluZXMgcHJvZ3JhbWF0aWNhbGx5IGFzIHlvdSBsb29rIGF0IGl0LgAAAAAAAwAAAAgAAAALAAAADQAAAAEAAAAQAAAAZGVzY3JpcHRpdmVUZXh0AAEAAAACAAAAAAAAAAMAAAANAAAABQAAAA0AAAAAAAAAAAAAAA==

Now, let's copy/paste that text into the luac json...

{
	"type": "ENTITY",
	"name":
	{
		"literalString" : "Shinier Gem"
	},
	"description":
	{
		"programString": true
	},
	"luac": "G0x1YVEAAQQEBAgAEAAAAEBzaGluaWVyR2VtLmx1YQAAAAAAAAAAAAAAAgIDAAAAJAAAAAcAAAAeAIAAAQAAAAQMAAAAZGVzY3JpcHRpb24AAQAAAAAAAAAFAAAADQAAAAAAAAIDAAAAAQAAAB4AAAEeAIAAAQAAAAQyAAAAVGhlIGdlbSBzaGluZXMgcHJvZ3JhbWF0aWNhbGx5IGFzIHlvdSBsb29rIGF0IGl0LgAAAAAAAwAAAAgAAAALAAAADQAAAAEAAAAQAAAAZGVzY3JpcHRpdmVUZXh0AAEAAAACAAAAAAAAAAMAAAANAAAABQAAAA0AAAAAAAAAAAAAAA=="
}

Testing

That's the finished JSON, ready for testing in-game! Use the UGC Control Panel as in the last tutorial, and when you look at the object in-game, the description should be "The gem shines programatically as you look at it." You just made a LUA object!

Video Guide

See this page to see a video demonstrating the compile/base64/run steps on Windows.