← Dialogue Documentation Home

Dialogue.Actor

Actor Overview

Actors are private instances which use messages to communicate with the company of actors, which controls all actor instances. Actors are empty containers which have all functionality given to them via scripts. Actors have no limit on the scripts they can possess. All actors have a unique id which is used to reference them throughout.

All functions and methods listed here are synchronous with exception of the actor:async, the tones and sometimes actor:remove.

Every method listed here is a valid method for an action.

Method Reference


Actor

Actor(actor_definition [, parent [, worker_id]])
Actor(actor_id)

This is the constructor for an Actor. It is created using the actor_definition, a table of script definitions, which is the only required argument.

The following is the formal actor_definition:

{ [script_definition1 [, ... [, script_definitionN]]] }

The parent can either be a number representing an actor's id or it can be an actor object returned from this function. When parent is supplied, the actor is created as a child of that parent. If parent is not supplied and no actors have been created, the created actor becomes the root of the company tree. Anytime after the root of the company has been created, if no parent is supplied, then the created actor implicitly becomes the child of the root.

The worker_id is a number representing which worker thread will handle all actions of the created actor. For example, if worker_id is 2 then the second worker thread will handle every action of the actor.

Every actor instance has a unique id which is handled by the company. The lifetime of an actor's instance is not related to the object returned from this function. If actor_id is the only argument supplied to this function, an object is returned that is a handler to the unique instance pointed to by that id.

Note that no scripts are loaded via this function. The actor is created in full and then is loaded. See actor:load, director and actions for more details.

Examples:

Actor{} -- returns a valid actor which has no scripts
test = Actor{ {"test-script"} }
test:id() -- returns 0
a0 = Actor(0)
a0 == test -- returns true
dungeon = Actor{ {"room", "dungeon.tile"}, {"exit", "south"} }
-- slime is a child of dungeon
slime = Actor({ {"monster", "slime"} }, dungeon)
-- create the Graphics actor with no parent (-1 means no actor)
-- does all actions on the first thread or worker
graphics = Actor({ {"graphics"} }, -1, 1)

↑ top


actor:load

actor:load()
actor:load(script_id)
actor:load("all")

This method loads the scripts of an actor. When an actor is created, all its scripts are marked to be loaded. No arguments need to be passed to load an actor which has never been loaded before. load does not normally need to be called after creating each actor unless the manual load option has been set.

When a script encounters an error, it is unloaded. To reload a specific script, pass the script_id which is simply the index of a script in the actor's definition table.

To forcefully reload all scripts, pass the string "all".

All scripts are reloaded using the actor's definition table passed to the Actor constructor.

Example:

a = Actor{ {"example-script", "foo"}, {"example-script", "bar"} }
a:load(1) -- reloads "foo"
a:load(2) -- reloads "bar"
a:load("all") -- reloads "foo" and "bar"

↑ top


actor:child

actor:child(actor_definition [, worker_id])

This method creates a new actor as a child of the method's caller. This method is an alias of Actor where the parent is explicitly defined, e.g. Actor(actor_definition, actor [, worker_id]).

Example:

dungeon = Actor{ {"room", "dungeon.tile"}, {"exit", "south"} }
-- slime is a child of dungeon
slime = dungeon:child{ {"monster", "slime"} }

↑ top


actor:children

actor:children()

Return the children of the actor as a table of actor ids.

Note that benched actors will not show up as a child.

Example:

actor = Actor{ {"example-script", "root"} }
actor:child{ {"example-script", "one"} }
actor:child{ {"example-script", "two"} }
actor:child{ {"example-script", "three"} }
actor:children() -- returns {1, 2, 3}

↑ top


actor:bench

actor:bench()

Bench an actor from the company. A benched actor will not receive (and thus not respond) to any messages.

A benched actor does not show up in the audience or children of any actor. A benched actor is still a valid actor and all methods here are valid for the actor, e.g. benching and then reloading an actor is valid.

While the benched actor exists outside the normal boundaries of the Dialogue it is able to be joined back into the company. See actor:remove to permanently remove an actor from the company.

Examples:

actor = Actor{ {"example-script", "zero"} }
actor:child{ {"example-script", "one"} }
second = actor:child{ {"example-script", "two"} }
actor:child{ {"example-script", "three"} }

-- bench the second actor, technically removing it as a child
second:bench()
actor:children() -- returns {1, 3}
actor = Actor{ {"example-script", "zero"} }
actor:child{ {"example-script", "one"} }
second = actor:child{ {"example-script", "two"} }
actor:child{ {"example-script", "three"} }

-- bench the second actor, removing it from any audience
second:bench()
actor:audience("command") -- returns {0, 1, 3}

↑ top


actor:join

actor:join([parent_id])

Join a benched actor back into the company. parent_id is an id of a valid actor.

If join is called without providing a parent_id then the actor is joined as a child of the parent it had when it was benched.

If parent_id is provided then it is joined as a child of the actor that corresponds with parent_id.

Examples:

parent = Actor{ {"example-script", "zero"} }
sibling_one = parent:child{ {"example-script", "one"} }
sibling_two = parent:child{ {"example-script", "two"} }

-- bench the first sibling
sibling_one:bench()
parent:children() -- returns {2}

-- and join it back to the company
sibling_one:join()
parent:children() -- returns {1, 2}
parent = Actor{ {"example-script", "zero"} }
sibling_one = parent:child{ {"example-script", "one"} }
sibling_two = parent:child{ {"example-script", "two"} }

-- bench the first sibling
sibling_one:bench()
parent:children() -- returns {2}

-- join as a child of sibling_two instead of parent
sibling_one:join(sibling_two)
parent:children() -- returns {2}
sibling_two:children() -- returns {1}

↑ top


actor:remove

actor:remove()

Permanently remove an actor from the company. This method is asynchronous if the actor has a specific thread requirement, i.e. worker_id was passed to the constructor. Otherwise it is a synchronous call.

Example:

parent = Actor{ {"example-script", "zero"} }
sibling_one = parent:child{ {"example-script", "one"} }
sibling_two = parent:child{ {"example-script", "two"} }

-- remove sibling_two from the company
sibling_two:remove()
parent:children() -- returns {1}

↑ top


actor:id

actor:id()

Return the id of an actor. See the company.

Example:

parent = Actor{ {"example-script", "zero"} }
sibling_one = parent:child{ {"example-script", "one"} }
sibling_two = parent:child{ {"example-script", "two"} }

parent:id() -- returns 0
sibling_one:id() -- returns 1
sibling_two:id() -- returns 2

↑ top


actor:parent

actor:parent()

Return the parent of an actor.

Example:

parent = Actor{ {"example-script", "zero"} }
sibling_one = parent:child{ {"example-script", "one"} }
sibling_two = parent:child{ {"example-script", "two"} }

-- '-1' represents the invalid id
parent:parent():id() -- returns -1
sibling_one:parent():id() -- returns 0
sibling_two:parent():id() -- returns 0

↑ top


actor:send

actor:send{ 'message' [, arg1 [, ... [, argn]]] [, author_id] }

Send a message to the actor. Messages and their handlers are defined by the scripts the actor possesses.

Sending a message to an actor which doesn't have a handler for that message is not an error but nothing occurs. For example, if the actor doesn't have a script which handles the "foo" message but receives one anyway, then it isn't an error.

Note that the author's id must be supplied if calling this method manually. Tones automatically append the author's id.

Example:

actor = Actor{ {"script-with-foo"} }
actor:send{ "foo", "Hello, World!" }
actor:send{ "bar", "Goodbye!" } -- no error, but nothing happens

↑ top


actor:probe

actor:probe(script_id, field)

Probe an actor's script for the value of field. field is the string associated with of the fields of the script's table. script_id is the index of a script in the actor's definition table.

Note that using this method for more than debugging or testing goes against the principles of Dialogue and will only cause harm in the long-term.

Example:

actor = Actor{ {"script-with-name", "robert"} }
actor:probe(1, "name") -- returns "robert"

-- update the script by sending a message to the Actor holding it
actor:send{ "set_name", "timothy" }
actor:probe(1, "name") -- returns "timothy"

↑ top


actor:async

actor:async(method [, arg1 [, ... [, argN]]])

Call a method asynchronously. method is any method of an actor listed here. This creates an action and gives it to the director.

If the actor has a worker requirement (worker_id was passed to the constructor) this method will automatically handle that requirement.

Example:

actor = Actor{ {"script-with-name", "robert"} }

-- asynchronously send a message 
actor:async("send", { "set_name", "timothy" })

-- asynchronously create a child
actor:async("child", { "script-with-name", "john" })

-- asynchronously remove the actor
actor:async("remove")

↑ top


actor:audience

actor:audience(tone)

Return a table of actor ids which that will receive a message sent via the tone. tone is one of the following four strings: "think", "say", "command", "yell".

The tone "whisper" is not valid here because the audience of a "whisper" is always specifically provided (rather than implicitly provided via a tone) and thus always known.

See the tone visualizer to better understand how tones affect the audience.

↑ top


actor:yell

actor:yell{ message [, arg1 [, ... [, argn]]] [, author_id] }

Asynchronously send a message to every actor in the company. actor is set as the author of the message. See send for information on how messages are received.

See the tone visualizer to visually see how yell affects how a message is sent.

↑ top


actor:command

actor:command{ message [, arg1 [, ... [, argn]]] }

Asynchronously send a message to the actor and all descendents of the actor. actor is set as the author of the message. See actor:send for information on how messages are received.

See the tone visualizer to visually see how command affects how a message is sent.

↑ top


actor:say

actor:say{ message [, arg1 [, ... [, argn]]] }

Asynchronously send a message to the actor, the actor's parent, and all siblings of the actor. actor is set as the author of the message. See actor:send for information on how messages are received.

See the tone visualizer to visually see how say affects how a message is sent.

↑ top


actor:whisper

actor:whisper(recipient, { message [, arg1 [, ... [, argn]]] })

Asynchronously send a message to recipient, an actor. actor is set as the author of the message. See actor:send for information on how messages are received.

↑ top


actor:think

actor:think{ message [, arg1 [, ... [, argn]]] }

Asynchronously have an actor send a message to itself. actor is set as the author of the message. See actor:send for information on how messages are received.

See the tone visualizer to visually see how think affects how a message is sent.

↑ top