Benutzer:Moerdn/ Blender 2.5 Feature Proposal

Proposal - Dupli Group references The ability to instantiate groups is great but the Blender Game Engine is missing necessary some support.

Terms

group object

a Blender object that is assigned to a group - it acts as template for instance objects

instance object

an object that is a copy of a group object created during instantiation

pivot

the instantiating object - it creates the instance objects via doubli group (usually an empty)

group instance

a pivot and a copy of all group objects of a group (instance objects)

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

# Code that shows adding of group instances
sce = bge.logic.getCurrentScene()
own = con.owner

#
# Add a dupligroup instance at the controller-owner location
#
dupli_group_pivot = sce.addObject("Instance", own)
#
# but no connection to the group objects
# dupli_group_pivot is 'useless' without references to 'its' group instances

Solution

with group patch

The solution provides an extended interface to the KX_GameObject class. There would be two new properties that give access and better control.

• pivot is a reference to the dupli-group if the object is part of the group instance
• instances is a python list that contains all objects if the object is the dupli-group object

In other cases (e.g. normal objects) these properties are None.

The implementation applies only to three files:

• KX_GameObject.h
  • declaration of the two private members CListValue* m_pInstanceObjects and KX_GameObject* m_pDupliGroupObject
  • declaration of four methods (get/set) and two python property declarations for the properties pivot and instances

• KX_GameObject.cpp
  • definition of the getter and setter as well as the python properts

• KX_Scene.cpp
  • two new lines in Method KX_Scene::DupliGroupRecurse that set the reference or add the object to the python list.

Python API Examples

With small changes to KX_GameObject class, the api provides two new attributes. So its fairly easy to figure out if an gameobject is part of a group:

# Determine whether the object belongs to a group instance
own = con.owner

if own.pivot is not None:
    # The object is part of a group instance.
    # own.pivot contains a reference to the 'creator', the pivot (the object with doubli-group).
else:
    # The object is not part of a group instance.

It is also easy to detect if the object is the pivot object:

# Determine whether the object is the pivot (the object with doubli-group)
own = con.owner

if own.instances is not None:
    # This object is a pivot that created a group instance.
    # own.instances contains a list of the objects of this particular group instance.
else:
    # This object is not a pivot

Be aware a pivot object can be part of another instance. That means both attributes can be set at the same time.

The attributes pivot and instances are read only.

# Read only values
own = con.owner

own.instances.append(obj) # cause a python exception, just as try to write the name property
own.pivot = foo # same here, not allowed

Benefits to Blender

• No guessing for the pivot 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 pivot wich makes it follow the pivots transformations
  • E.g. Follow the Pivots animation
• parent the pivot 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 Pivot and it's children can be "picked up" by the car.
• Accessing the pivots properties from any instance object
  • E.g. to read parameters for this instance ("speed", "stepSize")

Files, examples and further informations

• Videos on youtube to show this feature in action:
  • parenting instanced groups to other objects and instances on youtube
  • rearrange instanced group objects to new groups on youtube
  • parametrisable group instances on youtube
  • combine 'components' AND 'group referencing' in addition on youtube

• Patch for blender 2.5 trunk
• Patch for component branch

• windows build Build on Windows 7 32 Bit Blender 2.57.1

• example blendfiles
  • parenting instances of dupli-groups Blendfile
  • parametrisable particle system Blendfile
  • simple object access from dupli-group object Blendfile

back to Benutzer:Moerdn/ GameLogic