under constrution

Proposal - BGE Groups This is an alternative to the Moerdn's proposal This proposal shows a way to better support groups in the Blender Game Engine.

Terms

group member: a game object that is assigned to a group - it acts as template for instance objects
instance object: a game object that is a copy of a group object created during instantiation
instantiator: the instantiating object - it creates the instance objects via doubli group (usually an empty)
instance: an internal object that hold the relationship between the instantiator and the instantiated objects. The instance holds the instance properties
instance property: a property that is shared within a group instance
group property: a property that is shared within all group members

Blender GameEngine current situation

In Blender (3D View) the user is able to transform the instance objects via by performing transformations on the pivot. The instance objects are not accessible.

In the Game Engine the instance objects looses any relation to the pivot.

This is good in some situations:

The instance objects should exist as separate entities (e.g. as physics objects)

This is hard in other situations:

The instance objects should belong to the pivot and its parents in a perent relationship.
Moving the pivot should result in a move of the instance objects.
Objects parented to the pivot should be parented to one of the instance objects.

Problems

There is the option to establish the required relationship via Python API e.g. parenting. When doing this the problems show up:

there is no way to identify the instantiating object when an instance object is known
there is no way to identify the instance objects created by a particular instantiating object.
there is no way to identify other objects of the same instance
there is no method to share properties within an instance
there is no GUI element that allows to parent instance objects to the instantiator
there is no GUI element that allows to parent the instantiator an instance object

Solution

Access to the instance relationships

KX_Instance

The KX_Instance represents the instance of a group. It provides access to all instance related objects:

instantiator - (read only) reference to the KX_GameObject that created the group instance
instantiated- (read only) a list of KX_GameObject with instance objects belonging to this instance
group' - (read only)a reference to the KX_Group
attrDict - a dictionary of instance properties (shared withing the instances/instantiator)

On when instantiating a group instance in Blender the instance properties are added to the Game properties of the instantiator. The instance property can be changed via GUI. At instantiating the group in the BGE the value of the instantiator is used in the instance.

KX_Group

The KX_Group represents the a group. It provides access to all group related attributes:

name - the name of the group
instances- a list of instances created from this group

KX_GameObject

The solution provides an extended interface to the KX_GameObject class. There is a new attribute at the KX_GameObject acting as instanciator.

instantiating is a reference to the KX_Instance created by this object. None if this object is no instantiator.

There is a new attribute at the KX_GameObject acting as instance object.

instance is a reference to the KX_Instance that instantiated this object. None if this object is not an instance object.

An KX_GameObject can be instantiator and instance object at the same time.

Python API Examples

Game object is part of a group

own = con.owner

if own.instance is not None:
    print("The object", own.name, "is part of a group instance of group", own.instance.group.name,"instantiated by",own.instance.instantiator)
else:
    print("The object", own.name, "is not part of a group instance")

Game object is an instanctiating object

own = con.owner

if own.instantiating is not None:
    print("The object", own.name, "instantiated the group",own.instantiating.group.name)

else:
    print("The object", own.name, "did not instantiated a group")

Reading and writing instance properties

if own.instance is not None:
    instancePropertyValue = own.instance["instancePropertyName"]
    own.instance["instancePropertyName"] = "sharedValue"+own.name

Benefits to Blender

No guessing for the the instatiator anymore
No guessing for instance objects anymore
Easy to identify objects of the same instance that do not have a parent/child relationship
parent any instance object to the instatiator which makes it follow the instatiator transformations
- E.g. Follow the instatiator animation
parent the instatiator to any instance object which let the pivot follow the trasnformations of the is object.
- E.g. The instance object is a physics object (car) the instantiator and it's children can be "picked up" by the car.
Defining arguments with default values for a group (instance properties)
Option to set up individual parameters for a group instance

GUI enhancement

Property sensor