Benutzer:Monster~dewikibooks/ Blender Feature Proposal/BGE Groups

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

Dupli Group Instance

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:

1. there is no way to identify the instantiating object when an instance object is known
2. there is no way to identify the instance objects created by a particular instantiating object.
3. there is no way to identify other objects of the same instance
4. there is no method to share properties within an instance
5. there is no GUI element that allows to parent instance objects to the instantiator
6. 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