This page includes miscellaneous notes about the design of <harmony>.

Classes versus Interfaces

Should the specification use classes or interfaces?

There are three undesirable side effects that may be caused by the use of interfaces:

  1. Conceptual overload: potential, a programmer need to deal both with interfaces and the classes implementing such interfaces.
  2. Reduced portability: game code that subclasses vendor specific classes will be harder to port from one implementation to another.
  3. Broken window: where classes are forcibly used to program code, it is likely that those classes will give access to functionality that the original interfaces do not provide. Additionally, game programmers may be more tempted to cast interfaces to their actual implementers to access non standard functionality.
These side effects can be countered using a variant of the factory pattern – While the Play or Stage class may be created by a vendor specific factory, other objects would be created using methods like:
  • Stage.createActor()
  • Stage.createItem()
  • …
The downside of this pattern maybe that it discourages the use of subclassing as a means to customize types and extend the API.
Delegation is often safer than subclassing, however I do not think it would be reasonable to attempt discouraging subclassing altogether.

Enumerations

Enumerations cannot grow. In most cases where <harmony> requires enums, it is difficult to predict in advance what the enumerated elements will be. Examples

  • body parts
  • enumerated activity states (e.g. walking, running, striking, idle, …)

However enums are fast and conversions with int are transparent.

The <harmony> specification provides sample enumerations, however the actual types supported by the API are generic.

Mutability

In the original draft, I provided two actor interfaces, <Actor> and <MutableActor>. The question was to find out whether this distinction should be generalized or removed.

Pros and cons of distinguishing between mutable and immutable versions of entities:

Pro:

  • When a system’s dynamics become complex, it is often convenient to localize all write accesses to a given part of the system - the idea is a given part of the system processes events and modifies it’s own state in response to such events, rather than external modifications affecting the state of the object directly. Notably this makes coordinated state change easier.
  • Typically, simplifications and optimizations are possible when immutable states are known in advance.
Con:
  • The distinction is not intuitive.
  • In Objective C, it may be difficult to provide accessible properties while maintaining the above distinction. Properties, however, are convenient.

Provisionally the distinction will be removed. However, entities may be reformulated later on, using the following pattern:

  • @interface Actor <ReadableActor,WritableActor>

This allows resolving simple cases without worrying about the readable/writable distinction, while allowing game programmers to purposefully restrict access should they wish to do so.