← Dialogue Documentation Home

Dialogue.Actor.Script

Script Overview

The Script is what defines which messages an actor can receive and also how it might respond to a received message. This means there can be multiple scripts which handle the same message yet do so differently.

Scripts are made using the script constructor which is like a typical object-oriented programming class constructor. Message handlers of scripts are simply methods of that script.

The principle of scripts is founded in composition over inheritance. Actors are meant to reuse many scripts.


Script Definition

The formal definition of a script is as follows:

{ "module" [, arg1 [, ... [, argN]]] }

module is always a string and is the only required part of the definition. module must be a valid name of a Lua module. In our example script below, if it was a file named Foo.lua, its module name would be "Foo".

arg1 ... argN are optional arguments passed to the function defined in the constructor.

↑ top


Script Constructor

Script(script_name [,initializer_function])

This is a typical constructor that one would define for an object-oriented programming class.

script_name is a string that is the name of the script being defined. initializer_function is an anonymous function that is used to initialize new scripts with arguments. initializer_function can have any number of arguments but must always return a table.

Optionally, if no initializer_function is passed a blank table will be used as a constructor.

Script returns the script table which must be used to attach the message handlers. Message handlers are defined as Lua methods of that table. See messages below for more detail and also the example script.

See the actor constructor to create an actor out of scripts.

Examples:

Graphics = Script("Graphics", function(width, height)
    return { window = Window.new(width, height) }
end)
Player = Script("Player", function(string)
    return { name = string }
end)
-- No init function because it just listens
EventListener = Script("EventListener")

The following is a completed script:

Foo = Script("Foo", function(string)
    return { name = string }
end)

-- A message handler for `say_name'
-- note the ':' is used here instead of '.'
function Foo:say_name ()
    io.write(self.name)
end

-- A message handler for `set_name'
function Foo:set_name (string)
    self.name = string
end

-- this is always required
return Foo

↑ top


Messages

Messages follow a definition similar to the script's definition:

{ "method" [, arg1 [, ... [, argN]]] }

method is always a string and is the only required part of a message. method is simply the name of an script's message handler, which is a Lua method. arg1 ... argN are optional arguments passed to that handler.

There is no universal list of messages that must be updated to create new messages. If only a single script contains the method Foo:update then the update message is now a valid message for all of Dialogue.

Using the example script above, the following are valid messages:

{ "say_name" }
{ "set_name", "Marie" }
{ "set_name", "Thomas" }

Messages are the core of Dialogue. All messages are actions but not all actions are messages.

Messages are generally sent via tones which are a way to scope messages implicitly to the company. Messages are not sent to scripts themselves, but to actors. Scripts simply define how an actor handles a message. See actor:send to explicitly send an message to an actor.

There is no need to define an empty handler for a message if there is no need to handle that message. See an explanation for why no handler is needed below.

↑ top


Errors

Scripts are unloaded when an error occurs. An unloaded script still exists but doesn't handle messages until it is reloaded. One reason for this is robustness so that a single erroneous script doesn't cause any more harm. The other reason is that a script can be fixed and reloaded during runtime. See actor:load.

Using the example script above, the following invalid messages will cause the script to unload because it doesn't have the correct number of arguments: { "set_name" }.

Errors might also occur because of a malformed message handler such as a common syntax error.

Messages with no handler

If no message handler is defined for a particular message then no error occurs. The reasoning is that the responsibility is on the scripts to handle a message and that not handling a message is actually handling the message by doing nothing. For example, an actor which has a script that handles the move message internally without responding looks exactly the same as an actor which doesn't handle the move message at all -- they both don't respond in either case.

↑ top