Actor_Model_Introduction

Actor Mdoel Introduction

• Actor Mdoel Introduction
  • Overview
  • Functional Requirements
  • Actor Components - Properties and Methods
    • 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. 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++/Java 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) <= 1 Mb stripped.
• Approximate size of player data segment (dynamic allocation) requirements <= 256 Kb (stage instantiation, etc.).
• Runtime player can execute a title level at 30 fps with 1000 actor instances, with 100 actors with "trivial active behaviors/chores", with 20% CPU time available per frame.
• Core simulation player can load a title with 1000 actors and a 200K model in < 200% of the time that it would take to read that amount of raw data in from external media.

Actor Components - Properties and Methods

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, messages 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 (homogenous 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-homogenous 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 modeled after fields in SGI's Open Inventor. Inventor supports a limited 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 analogous to C++ public and protected fields. Globally defined properties in an actor are visible 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 authoring 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 journaling 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.

Because 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 method name like "_init" or "INIT". It is desirable to allow multiple methods 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 limited 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 value 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 attaching a new evaluator detaches the old one. The common use for evaluators is for interpolating property values over time.

Typically, evaluators 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. Evaluators 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 (instead 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 definitions, functions, and scripts that can be attached to an actor class at authoring time. Properties defined in a package are added to the actor class definition (unless they already exist there, in which cast they are ignored). Functions and scripts in a package are added to the actor class definition as methods. Normally, the components of a package will work together to add some sort of functionality, such as a behavior. When installed, package methods can be accessed just like local methods defined within the actor.

Packages can be removed from an actor class definition at authoring time. Note that intermixing the creation of actor instances with editing the actor class definition might lead to the existence of actors of a single class with differing composition. This is an artifact of the flexibility of the Magic Lantern authoring process. The potential non-homogeneity of same-class actors is temporary and will disappear when the title is restarted.

In order for packages to have any noticeable effect, they must somehow communicate their actions. For access to other actors, package methods can use the API available to all methods to send messages, get and set properties, and call methods. Unlike local methods, however, package methods are restricted to this same access to the local actor, i.e. they cannot use the intrinsic access mechanisms or get at private (locally defined) properties.

The mechanism used to change the state of an actor is the property interface. Package methods change property values, which may affect presentation or other behavior. Any properties that a package accesses should be declared in the package. These must be globally defined properties, so it is an error to have a property definition in a package that conflicts with an existing globally defined property. Package properties that have not been previously installed on the title are newly registered as globally defined properties.