Dynamic Number of Action Layers #39572

New Issue

Kevin Ednalino · 2014-04-03T02:27:12+02:00

Kevin Ednalino commented

2014-04-03 02:27:12 +02:00

Patch: D211

Summary:
This patch removes the limitations on the number of action layers in the BGE.

Implementation:
BL_ActionManager currently creates a variable called m_layers which is a fixed array of BL_Action. This variable is used to keep track of the action layers. This patch replaces the fixed array with a variable called m_actions which is of type BL_ActionList. BL_ActionList is a Vector of type BL_Action* defined in BL_Action.h. This allows for dynamic allocation of action layers.

Features:

Adds 3 new methods to the KX_GameObject class: addAction(), removeAction(layer), and isActionValid(layer)
- addAction - appends a new item to m_layers and returns the index of the new layer.
- removeAction - erases the layer at the specified position if valid. These methods allow the user to manage actions similar to the way scenes are managed. However, erasing a layer means the Vector will be resized, so user needs to keep in mind the index changes after removing.
- isActionValid - checks if the specified layer is within m_layers.
User needs to call addAction before using the other methods like playAction, etc. If user calls one of those methods on a non-existent layer, the error will be caught and the user notified.
The actuator will automatically create the layer if it doesn't exist.

Concerns:

When removing elements that are not at the beginning or end of the vector, possibly resizing the vector can be significant, O(N) time. However, I believe this only becomes an issue with an extremely high amount of layers.
Currently with the actuator, there is no way to remove the layer. See Future section.

Future:

Add option to action actuator, to remove specified layer when the animation is done.
Add method to retrieve m_layers as a list object in Python.
Add method to clear layers whose animations have finished.
Expose BL_Action so user can create an Action object and pass it to addAction.

0001-Dynamic-Number-of-Action-Layers.patch

Patch: [D211](https://archive.blender.org/developer/D211) **Summary:** This patch removes the limitations on the number of action layers in the BGE. **Implementation:** BL_ActionManager currently creates a variable called m_layers which is a fixed array of BL_Action. This variable is used to keep track of the action layers. This patch replaces the fixed array with a variable called m_actions which is of type BL_ActionList. BL_ActionList is a Vector of type BL_Action* defined in BL_Action.h. This allows for dynamic allocation of action layers. **Features:** - Adds 3 new methods to the KX_GameObject class: addAction(), removeAction(layer), and isActionValid(layer) - addAction - appends a new item to m_layers and returns the index of the new layer. - removeAction - erases the layer at the specified position if valid. These methods allow the user to manage actions similar to the way scenes are managed. However, erasing a layer means the Vector will be resized, so user needs to keep in mind the index changes after removing. - isActionValid - checks if the specified layer is within m_layers. - User needs to call addAction before using the other methods like playAction, etc. If user calls one of those methods on a non-existent layer, the error will be caught and the user notified. - The actuator will automatically create the layer if it doesn't exist. **Concerns:** - When removing elements that are not at the beginning or end of the vector, possibly resizing the vector can be significant, O(N) time. However, I believe this only becomes an issue with an extremely high amount of layers. - Currently with the actuator, there is no way to remove the layer. See *Future* section. **Future:** - Add option to action actuator, to remove specified layer when the animation is done. - Add method to retrieve m_layers as a list object in Python. - Add method to clear layers whose animations have finished. - Expose BL_Action so user can create an Action object and pass it to addAction. [0001-Dynamic-Number-of-Action-Layers.patch](https://archive.blender.org/developer/F83823/0001-Dynamic-Number-of-Action-Layers.patch)

Kevin Ednalino commented

2014-04-03 02:27:12 +02:00

Changed status to: 'Open'

Mitchell Stokes was assigned by Kevin Ednalino

2014-04-03 02:27:12 +02:00

Kevin Ednalino commented

2014-04-03 02:27:12 +02:00

Added subscriber: @mahalin

Kevin Ednalino commented

2014-04-04 04:15:01 +02:00

Version 2:

I removed the addAction and removeAction methods from the Python API as I thought this was cumbersome -> too much boilerplate code.
- So like before, the user calls playAction which plays the action but it will also create the layer if it doesn't exist. Additionally, it will return the layer number in case the user needs verification. However, the other methods, e.g. stopAction, getActionFrame, etc. will throw an error if the specified layer does not exist, rather than create it automatically like playAction; there really should be only one way to create the layer. This is better than passively handling it so the user doesn't wonder why the animation isn't playing (because they didn't play/create it first).
- I left isActionValid so the user can check beforehand if needed, otherwise the error will stop the script.
I added getActionList(), to allow the user to retrieve the list of actions.
- It returns a list of the current frames of the action for that layer (index). My preference is to properly expose BL_Action, which is my next task.
When the update method of BL_ActionManager is called, it removes the layer from the list if the animation is done.
- Some concerns remain about this. Another possibility is to have the user specify whether they want the layer to be automatically removed upon the animation ending, however I think the user need not be this concerned about memory management.

0001-Dynamic-Number-of-Action-Layers.patch

Version 2: - I removed the addAction and removeAction methods from the Python API as I thought this was cumbersome -> too much boilerplate code. - So like before, the user calls playAction which plays the action but it will also create the layer if it doesn't exist. Additionally, it will return the layer number in case the user needs verification. However, the other methods, e.g. stopAction, getActionFrame, etc. will throw an error if the specified layer does not exist, rather than create it automatically like playAction; there really should be only one way to create the layer. This is better than passively handling it so the user doesn't wonder why the animation isn't playing (because they didn't play/create it first). - I left isActionValid so the user can check beforehand if needed, otherwise the error will stop the script. - I added getActionList(), to allow the user to retrieve the list of actions. - It returns a list of the current frames of the action for that layer (index). My preference is to properly expose BL_Action, which is my next task. - When the update method of BL_ActionManager is called, it removes the layer from the list if the animation is done. - Some concerns remain about this. Another possibility is to have the user specify whether they want the layer to be automatically removed upon the animation ending, however I think the user need not be *this* concerned about memory management. [0001-Dynamic-Number-of-Action-Layers.patch](https://archive.blender.org/developer/F83907/0001-Dynamic-Number-of-Action-Layers.patch)

Kevin Ednalino commented

2014-04-07 05:12:11 +02:00

Version 3:

BL_Action is now a game type (subclass of PyObjectPlus)
- Methods: play, stop, isPlaying. The other former methods of KX_GameObject, i.e. getActionFrame, can be accessed through the attributes.
- Attributes: name, layer (RO), frame, frameStart, frameEnd, priority, blendIn, playMode, layerWeight, ipoFlags, playbackSpeed, blendMode.
Simplified the action related functions in KX_GameObject to only 3: getActionList, isActionValid, createAction.
getActionList returns a list of BL_Action objects. The name of the action is used as the name representation.
isActionValid checks if the specified layer is valid; could be removed as the user could just get the action list and check the length.
createAction is similar to playAction, without the layer argument and it returns a BL_Action object instead of a layer (layer can be accessed with BL_Action.layer)
It was renamed because it made more sense than playAction or addAction. To me, addAction implies adding an action object from a preexisting list of objects, like addScene.
How it works: The user calls createAction -> calls AddAction and then PlayAction -> returns newly created BL_Action object.
To explicitly remove a layer, call BL_Action.stop() on the layer and it will automatically be removed on the next BL_ActionManager.Update.

Future:

Add functions to allow moving layers, e.g. moveAbs, moveRel, swapPos, etc.

Version 4 (upcoming):

Minor change: BL_Action's "playbackSpeed" will be renamed to "speed".

Just saw Moguri's multithreaded animations update, will update accordingly.

0001-Dynamic-Number-of-Action-Layers-v3.patch

Version 3: - BL_Action is now a game type (subclass of PyObjectPlus) - Methods: play, stop, isPlaying. The other former methods of KX_GameObject, i.e. getActionFrame, can be accessed through the attributes. - Attributes: name, layer (RO), frame, frameStart, frameEnd, priority, blendIn, playMode, layerWeight, ipoFlags, playbackSpeed, blendMode. - Simplified the action related functions in KX_GameObject to only 3: getActionList, isActionValid, createAction. - getActionList returns a list of BL_Action objects. The name of the action is used as the name representation. - isActionValid checks if the specified layer is valid; could be removed as the user could just get the action list and check the length. - createAction is similar to playAction, without the layer argument and it returns a BL_Action object instead of a layer (layer can be accessed with BL_Action.layer) - It was renamed because it made more sense than playAction or addAction. To me, addAction implies adding an action object from a preexisting list of objects, like addScene. - How it works: The user calls createAction -> calls AddAction and then PlayAction -> returns newly created BL_Action object. - To explicitly remove a layer, call BL_Action.stop() on the layer and it will automatically be removed on the next BL_ActionManager.Update. Future: - Add functions to allow moving layers, e.g. moveAbs, moveRel, swapPos, etc. Version 4 (upcoming): - Minor change: BL_Action's "playbackSpeed" will be renamed to "speed". Just saw Moguri's multithreaded animations update, will update accordingly. [0001-Dynamic-Number-of-Action-Layers-v3.patch](https://archive.blender.org/developer/F84161/0001-Dynamic-Number-of-Action-Layers-v3.patch)

Mitchell Stokes commented

2014-04-10 01:49:23 +02:00

All of these patches break existing scripts (i.e., they change the API). Also, it's really best to have a patch fix/change one thing at a time. This is turning into a complete refactor of the Python animation API when the original intent was to have a more flexible limit of action layers. So, I will begin by just addressing your first patch.

This patch breaks the existing API. For example, if I cannot play animations on arbitrary layers, I have to first add the layers. And what if I do not want to add the layers in order? I'm not entirely sure on the use case for non-consecutive layers, but the old API supported it. I think it would be better to have the action manager automatically handle adding and removing layers. Also, using a map would allow for sparse layer allocation.

All of these patches break existing scripts (i.e., they change the API). Also, it's really best to have a patch fix/change one thing at a time. This is turning into a complete refactor of the Python animation API when the original intent was to have a more flexible limit of action layers. So, I will begin by just addressing your first patch. This patch breaks the existing API. For example, if I cannot play animations on arbitrary layers, I have to first add the layers. And what if I do not want to add the layers in order? I'm not entirely sure on the use case for non-consecutive layers, but the old API supported it. I think it would be better to have the action manager automatically handle adding and removing layers. Also, using a map would allow for sparse layer allocation.

Kevin Ednalino commented

2014-04-10 03:41:45 +02:00

The latest patch (v3) supersedes the others. v3 automates the adding and removal of layers since that was too much boilerplate code. I guess it is a refactor then? For future reference, I'll keep that in mind.

Proposed changes for v4 (relative to v3):

Leave playAction as playAction instead of renaming it to createAction.
Leave layer argument so it works like previous except it'll automatically create the layer if it doesn't exist.
In that case, playAction should return the layer number since the layer the user specifies may not exist. For example, the first time they call playAction(layer=10), but no layers have been created so it's actually performed on layer 0.
What about the bool for whether action played or not?
Change ActionList from Vector -> Map; forgot about this.
PEP-8 style for BL_Action.

The first two changes should maintain backwards compatability and work as expected.

By exposing BL_Action, we could remove some of the action functions out of KX_GameObject. Although, we could leave in the old functions for backwards compatability but that seems redundant...two ways to do the same thing?

As for breaking the API, I'm not completely sure what the rules are on that. I've been looking around, e.g. new developer guides etc. but haven't found anything definitive. AFAIK, we try to maintain as much backwards compatability as possible?

http://code.blender.org/index.php/2013/06/blender-roadmap-2-7-2-8-and-beyond/
2.7 allowed to break API?

The latest patch (v3) supersedes the others. v3 automates the adding and removal of layers since that was too much boilerplate code. I guess it is a refactor then? For future reference, I'll keep that in mind. Proposed changes for v4 (relative to v3): - Leave playAction as playAction instead of renaming it to createAction. - Leave layer argument so it works like previous except it'll automatically create the layer if it doesn't exist. - In that case, playAction should return the layer number since the layer the user specifies may not exist. For example, the first time they call playAction(layer=10), but no layers have been created so it's actually performed on layer 0. - What about the bool for whether action played or not? - Change ActionList from Vector -> Map; forgot about this. - PEP-8 style for BL_Action. The first two changes should maintain backwards compatability and work as expected. By exposing BL_Action, we could remove some of the action functions out of KX_GameObject. Although, we could leave in the old functions for backwards compatability but that seems redundant...two ways to do the same thing? As for breaking the API, I'm not completely sure what the rules are on that. I've been looking around, e.g. new developer guides etc. but haven't found anything definitive. AFAIK, we try to maintain as much backwards compatability as possible? http://code.blender.org/index.php/2013/06/blender-roadmap-2-7-2-8-and-beyond/ 2.7 allowed to break API?

Kevin Ednalino commented

2014-04-17 01:32:25 +02:00

Alright, I broke down the patch into 3 parts. To keep it simple, I'll only attach patch #1 in this task and create separate tasks for the other two, and keep the discussion of this task to patch #1.

Patch #1: 0001-BGE-Dynamically-allocated-action-layers.patch

BL_ActionManager->m_layers is now a BL_ActionMap.
BL_ActionMap is defined in BL_Action.h. It has short,BL_Action* key-value pair.
MAX_ACTION_LAYERS changed to max size of a short (32767).
KX_GameObject's playAction will automatically create the given layer if it doesn't exist. The actual creation is handled by BL_ActionManager::PlayAction.
BL_ActionManager::Update() will delete the layer if the animation is done.
Added 3 functions to BL_ActionManager: IsActionValid() and AddAction(), RemoveAction(). These are only used by BL_ActionManager and BL_ActionActuator.
BL_ActionActuator::Update() will also create the layer if it doesn't exists.

The Python API was not changed and the action system should remain backwards compatible and function as expected.

Patch #2 will add additional action-related methods to KX_GameObject and patch #3 will create new game type - BL_Action, and possibly a fourth patch for cleanup.

Alright, I broke down the patch into 3 parts. To keep it simple, I'll only attach patch #1 in this task and create separate tasks for the other two, and keep the discussion of this task to patch #1. Patch #1: [0001-BGE-Dynamically-allocated-action-layers.patch](https://archive.blender.org/developer/F85033/0001-BGE-Dynamically-allocated-action-layers.patch) - BL_ActionManager->m_layers is now a BL_ActionMap. - BL_ActionMap is defined in BL_Action.h. It has short,BL_Action* key-value pair. - MAX_ACTION_LAYERS changed to max size of a short (32767). - KX_GameObject's playAction will automatically create the given layer if it doesn't exist. The actual creation is handled by BL_ActionManager::PlayAction. - BL_ActionManager::Update() will delete the layer if the animation is done. - Added 3 functions to BL_ActionManager: IsActionValid() and AddAction(), RemoveAction(). These are only used by BL_ActionManager and BL_ActionActuator. - BL_ActionActuator::Update() will also create the layer if it doesn't exists. The Python API was not changed and the action system should remain backwards compatible and function as expected. Patch #2 will add additional action-related methods to KX_GameObject and patch #3 will create new game type - BL_Action, and possibly a fourth patch for cleanup.

Mitchell Stokes commented

2014-05-08 05:50:36 +02:00

Changed status from 'Open' to: 'Resolved'

Mitchell Stokes closed this issue

2014-05-08 05:50:36 +02:00

Mitchell Stokes commented

2014-05-08 05:50:36 +02:00

The patch has been committed.

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Dynamic Number of Action Layers #39572