View source for 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.

<syntaxhighlight lang="json">
{
	"type": "ENTITY",
	"name":
	{
		"literalString" : "Shinier Gem"
	},
	"description":
	{
		"programString": true
	},
	"lua": "???"
}
</syntaxhighlight>

== Writing the LUA code ==

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

<syntaxhighlight lang="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
</syntaxhighlight>

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 [https://www.freeformatter.com/json-escape.html this]. 

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

 <code>-- 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</code>

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

<syntaxhighlight lang="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"
}
</syntaxhighlight>

== 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!