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 lua. That is the json escaped version of the lua source code. Let's generate that in the next step.

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

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

Now, let's put this into the JSON. We will need to escape this source code so it can be pasted in the lua field. Some advanced text editors will have a "JSON Escape" feature, or just use a website like this.

Doing so will result in a very long line of text like so:

-- Description is called when an object's description is shown to the\r\n-- player or otherwise requested.  The object should return a string\r\n-- containing the description.\r\n\r\nfunction description()\r\n\r\n   -- Create a descriptive string\r\n   local descriptiveText = \"The gem shines programatically as you look at it.\";\r\n\r\n   -- Return it\r\n   return descriptiveText;\r\n\r\nend

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

{
	"type": "ENTITY",
	"name":
	{
		"literalString" : "Shinier Gem"
	},
	"description":
	{
		"programString": true
	},
	"lua": "-- Description is called when an object's description is shown to the\r\n-- player or otherwise requested.  The object should return a string\r\n-- containing the description.\r\n\r\nfunction description()\r\n\r\n   -- Create a descriptive string\r\n   local descriptiveText = \"The gem shines programatically as you look at it.\";\r\n\r\n   -- Return it\r\n   return descriptiveText;\r\n\r\nend"
}

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!