Actor_Model_Introduction

• Overview
• Functional Requirements
  • Components of the Actor
    • Properties
    • Property Access
    • Methods
    • Evaluators
    • Packages

Overview

Actors are the principal operational elements in Magic Lantern and provide the fundamental programming abstraction and compositional unit. The granularity of actors in a title is determined by the title author. A brick, a wall, or an entire building could be reasonably implemented as a single actor, depending on title requirements. Practical limits of space, time, and conceptual complexity will constrain what actors will be. However, the authoring architecture imposes no overriding constraints.

The goals of the actor object model design are to:

• create a set of abstractions of a world sufficient to express most common application entities and their inter-relationships,
• provide flexibility in the construction, editing and debugging of actors and titles at authoring time, and
• allow creation of efficient mastered titles.

The actor design expresses an object model in which actor state is embodied as properties, and methods determine how the actor responds to stimuli.

The Magic Lantern actor object model is implemented in C and Java, depending on the platform the title author is targeting. For native platforms, the implementation is in C rather than C++, despite the fact that C++ more directly supports object-oriented abstractions. The requirement to use C instead of C++ emerges from the needs and expectations of some of the target users of Magic Lantern, console game developers. Though using C to do object-oriented programming is more difficult, with a well structured design it need not be overly burdensome to the title developer.

The Magic Lantern object model, like that of C++, provides for abstraction, encapsulation and inhereitance. The Magic Lantern model is simpler than that of C++ in that it supports only single inheritance. It is also only an object model. It doesn't attempt to provide analogs to C++ language features like operator overloading.

Actors are also containers for other actors. At runtime, actors will be organized to represent containership, inherited geometrical relationships. At the present time, the design is to support a tree structure rooted by an actor that contains state and features for the entire title. An alternative is a more general directed graph. In either case, Magic Lantern will provide mechanisms for traversing and editing aactor containership hierarchies.

Functional Requirements

• Properties and methods can be added at authoring time, exetnding actors that have been previously compiled.
• Properties and methods can be accessed by external objects that know the owner is an actor, but don't have knwoledge of the specific type of actor.
• Actors can define local properties that have their own namespace and are accessible only by the actor itself or other actors with special knowledge of this particular actor type.
• Property and method access within an actor, or by objects that are familiar with the specific actor type (by including its header file), is efficient.
• Methods can be implemented in actor source code (C code attached to an actor as part of its definition), in compiled code added at authoring time, or in scripts.
• Actor overhead is low, meaning that an actor that contains nothing and does nothing is very efficient in time and space.
• Approximate size of player libraries and binary (text segment)

Note: the current implementation of the actor model does not yet address all of these features. Specifically, support has not yet been developed for scores, scripts and evaluators.

Actors are containers for properties and methods. Properties and methods correspond to C++ and Java class member variables and member functions. Like member variables, properties embody an actor's state. Like member functions, an actor's methods determine what an actor does.

Actors have dictionaries for properties and methods that allow lookup by name. In implementation, what these dictionaries hold are pointers (C) or references (Java) to objects, either properties or functions. These dictionaries and their loading are discussed in greater detail in the sections that follow.

Components of the Actor

Properties

Magic Lantern defines a small set of property types that may be single or multi-valued (homegenous arrays):

• unsigned byte
• signed 16 bit integer
• signed 32 bit integer
• float
• string
• position (3D)
• color
• orientation (quaternion)
• transform
• media reference
• actor pointer

Arbitrary non-homegenous aggregate property structures (like user-defined C structures) will not be supported. User-defined property types are not support in the first release.

To some degree, Magic Lantern properties are modelled after fields in SGI's Open Inventor. Inventor supports a limitied number of datatypes for fields (though Inventor allows extension of this list), both single and multi-valued. Inventor fields transcribe their own values in, and represent the state of the node. Unlike Inventor fields, however, properties are not smart objects. They do not, for instance, support notification except at authoring time for debugging purposes.

The actor model provides for a simple two-level scoping mechanism for properties. All actors have dictionaries for both locally and globally defined objects. Globally defined properties have a common meaning throughout a title. Access to properties installed on an actor as global is permitted by any actor in a title. Local properties have a definition which is local to the actor in which they are defined. Local properties can only be accessed by an actor and its friends (that is, other actors that include the header file that defines the original actor).

This scoping model is somewhat analagous to C++ public and protected fields. Globally defined properties in an actor are visibile to all other actors, like public fields. Locally defined properties are visible to subclassed objects, like protected fields. Locally defined propertied may also be accessed from actors that make a special relationship with that actor class, like friend classes in C++. Unlike C++, publicly visible properties have their types globally defined. Also unlike C++, the designation of who is a "friend" is done by the friend class and not the class whose protected members require access.

Property Access

A fundamental requirement of the design is that property access must be performed by the same programming model in the auhtoring and the mastering environment. That is, the actor code written for authoring must make the transition to the delivery platform without requiring any user modification.

Property access from C code will be via a set of Magic Lantern-supplied macros. In the authoring environment, these macros will allow property access to be instrumented for the sake of journalling and watchpoint debugging. A set of built-in functions provides for property access from within the scripting language.

Properties are classified as either intrinsic or extrinsic depending on how they become attached to actors (note that a property by itself is not considered either intrinsic or extrinsic apart from the details of how it is attached to actors). Intrinsic properties are statically defined in the C code that specifies an actor's basic capabilities. Extrinsic properties are added to an actor dynamically and are not part of the C-based specification of the actor.

The advantage to using intrinsic properties is that the properties may be accessed by C-based actor code directly, instead of through property lookup service. It is expected that all properties in mastered titles will be intrinsic properties.

The advantage of extrinsic properties is that they permit late binding to the actor. During the authoring process, authors can add properties to actor classes without requiring that the actor classes be recompiled and reloaded into the title.

Methods

Methods are defined on a class-wide basis for actors in the title. Methods are attached to actors by placing both the method name and a pointer to the function implementing the method in an actor class's method dictionary.

Methods are registered with argument and return value information, so that calls, from scripts in particular, can do type checking. Core dumps from ill-formed scripting calls are not acceptable. The argument typing is also useful when methods are registered to be executed in response to incoming messages. A message of a particular type has associated data in the message body. This data becomes the arguments to the methods invoked (more than one method can be installed into a message handler slot). Arguments for the methods must match the incoming data in the message; argument registration provides the mechanism to ensure this.

Becuase methods are stored in a name keyed dictionary, they can be dynamically accessed by name. Actor code desiring fact method access may retrieve and hold method identifiers. This is discussed at greatre length in the section on messaging.

Through the method table is specified on a class-wide basis, each actor instance contains a message handler table. This table establishes bindings between particular message types and one or more methods. This table is dynamic and can be changed both at authoring and title execution time.

Like properties, methods can be bound to an actor class in the authoring environment after the source code has been compiled.

There is a special naming convention on methods that specifies that certain methods be executed when an actor is created and another convention to specify methods to be executed on destruction. The convention will probably be a special suffix on the mehtod name like "_init" or "INIT". Is is desirable to allow multiple metods to be called in this way because independent sets of methods, called packages, can be installed on actors. This convention will allow packages to initialize themselves, for example registering with a message list and installing methods into handler slots, without causing any name collisions.

Methods can be given a priority at authoring time, which specifies the order of execution when multiple methods are placed in a message handler slot. These relative priorities are fixed at authoring time, and are not negotiated on method installation as a message handler. This feature accommodates a limitied means of mixing behavior that affect common state, where methods that run later override the state settings of methods that run earlier.

Evaluators

Evaluators are pieces of code attached to a single property that update the vlaue on some regular basis, e.g. every frame. Evaluators are specific to a particular property datatype, and know how to interpret their own specification in the workprint. They are purely a convenience; evaluators have no capabilities that cannot be performed with methods.

Evaluators are attached to or deleted from a property. At most one evaluator can be attached to a property at one time; the act of attahing a new evaluator detaches the old one. The common use for evaluators is for interpolating property values over time.

Typically, evaulators are attached and detached by scores. The score contains the attachment command and identifies the evaluator, and the evaluator reads its own specific parameters. For an interpolating evaluator, this would likely be a set of times and values. Once attached, the evaluator is run on a regular basis, e.g. on every execution cycle, compute a new value, and updates the property. Evaulators may detach themselves when complete or be detached from a score or other actor code.

While a set of evaluators that perform different kinds of interpolation on all property data types will be supplied with the system, authors may also write their own special purpose evaluators (in C or Java). User-written evaluators must include an initialization function for registration, a parser to read parameters in from the workprint, a construction function to build instances from actor code (instad of from an evaluator score action), and a function that performs the computation and updates the property value.

Packages

A package is a group of property defintions, functions, and scripts that can be attached to an actor class at authoring time.