BGE: bookmark option on controller to make them run before all other controllers.

A new bookmark button is available on the controller UI. 
When set, the controller is guaranteed to execute before all
other non-bookmarked controllers, provided it is scheduled 
for execution. 

This is useful for initialization scripts that run once at startup or
scripts that must set some prerequisite for the other controllers at
the start of each logic frame.

This feature is also available at python level with the "bookmark"
attribute. It can be changed during the game.

Note that if several script are bookmarked, their relative order of 
execution is not guaranteed. Make sure they don't depend on each other.

9 files changed, 43 insertions, 8 deletions

diff --git a/source/blender/makesdna/DNA_controller_types.h b/source/blender/makesdna/DNA_controller_types.h
index b3c82e746c1..599bbf9653a 100644
--- a/source/blender/makesdna/DNA_controller_types.h
+++ b/source/blender/makesdna/DNA_controller_types.h
@@ -79,6 +79,7 @@ typedef struct bController {
 #define CONT_DEL		2
 #define CONT_NEW		4
 #define CONT_MASK		8
+#define CONT_PRIO		16
 
 /* pyctrl->flag */
 #define CONT_PY_DEBUG	1
diff --git a/source/blender/src/buttons_logic.c b/source/blender/src/buttons_logic.c
index a537d32feae..b229fe440a5 100644
--- a/source/blender/src/buttons_logic.c
+++ b/source/blender/src/buttons_logic.c
@@ -3788,6 +3788,7 @@ void logic_buts(void)
 						uiBlockSetEmboss(block, UI_EMBOSSM);
 						uiDefIconButBitS(block, TOG, CONT_DEL, B_DEL_CONT, ICON_X,	xco, yco, 22, 19, &cont->flag, 0, 0, 0, 0, "Delete Controller");
 						uiDefIconButBitS(block, ICONTOG, CONT_SHOW, B_REDR, ICON_RIGHTARROW, (short)(xco+width-22), yco, 22, 19, &cont->flag, 0, 0, 0, 0, "Controller settings");
+						uiDefIconButBitS(block, TOG, CONT_PRIO, B_REDR, ICON_BOOKMARKS, (short)(xco+width-66), yco, 22, 19, &cont->flag, 0, 0, 0, 0, "Bookmarl controller to run before all other non-bookmarked controllers on each logic frame");
 						uiBlockSetEmboss(block, UI_EMBOSSP);
 						sprintf(name, "%d", first_bit(cont->state_mask)+1);
 						uiDefBlockBut(block, controller_state_mask_menu, cont, name, (short)(xco+width-44), yco, 22, 19, "Set controller state index (from 1 to 30)");
@@ -3796,7 +3797,7 @@ void logic_buts(void)
 						if(cont->flag & CONT_SHOW) {
 							cont->otype= cont->type;
 							uiDefButS(block, MENU, B_CHANGE_CONT, controller_pup(),(short)(xco+22), yco, 70, 19, &cont->type, 0, 0, 0, 0, "Controller type");
-							but= uiDefBut(block, TEX, 1, "", (short)(xco+92), yco, (short)(width-136), 19, cont->name, 0, 31, 0, 0, "Controller name");
+							but= uiDefBut(block, TEX, 1, "", (short)(xco+92), yco, (short)(width-158), 19, cont->name, 0, 31, 0, 0, "Controller name");
 							uiButSetFunc(but, make_unique_prop_names_cb, cont->name, (void*) 0);
 				
 							ycoo= yco;
@@ -3808,7 +3809,7 @@ void logic_buts(void)
 							glRecti(xco+22, yco, xco+width-22,yco+19);
 							but= uiDefBut(block, LABEL, 0, controller_name(cont->type), (short)(xco+22), yco, 70, 19, cont, 0, 0, 0, 0, "Controller type");
 							uiButSetFunc(but, sca_move_controller, cont, NULL);
-							but= uiDefBut(block, LABEL, 0, cont->name,(short)(xco+92), yco,(short)(width-136), 19, cont, 0, 0, 0, 0, "Controller name");
+							but= uiDefBut(block, LABEL, 0, cont->name,(short)(xco+92), yco,(short)(width-158), 19, cont, 0, 0, 0, 0, "Controller name");
 							uiButSetFunc(but, sca_move_controller, cont, NULL);
 							ycoo= yco;
 						}
diff --git a/source/gameengine/Converter/KX_ConvertControllers.cpp b/source/gameengine/Converter/KX_ConvertControllers.cpp
index 9b0e27b573a..85ab8e4f8b8 100644
--- a/source/gameengine/Converter/KX_ConvertControllers.cpp
+++ b/source/gameengine/Converter/KX_ConvertControllers.cpp
@@ -199,6 +199,7 @@ void BL_ConvertControllers(
 		{
 			LinkControllerToActuators(gamecontroller,bcontr,logicmgr,converter);
 			gamecontroller->SetExecutePriority(executePriority++);
+			gamecontroller->SetBookmark((bcontr->flag & CONT_PRIO) != 0);
 			gamecontroller->SetState(bcontr->state_mask);
 			STR_String uniquename = bcontr->name;
 			uniquename += "#CONTR#";
diff --git a/source/gameengine/GameLogic/SCA_IController.cpp b/source/gameengine/GameLogic/SCA_IController.cpp
index f8b081ef050..84a6bfb8085 100644
--- a/source/gameengine/GameLogic/SCA_IController.cpp
+++ b/source/gameengine/GameLogic/SCA_IController.cpp
@@ -244,6 +244,7 @@ PyAttributeDef SCA_IController::Attributes[] = {
 	KX_PYATTRIBUTE_RO_FUNCTION("state", SCA_IController, pyattr_get_state),
 	KX_PYATTRIBUTE_RO_FUNCTION("sensors", SCA_IController, pyattr_get_sensors),
 	KX_PYATTRIBUTE_RO_FUNCTION("actuators", SCA_IController, pyattr_get_actuators),
+	KX_PYATTRIBUTE_BOOL_RW("bookmark",SCA_IController,m_bookmark),
 	{ NULL }	//Sentinel
 };
 
diff --git a/source/gameengine/GameLogic/SCA_IController.h b/source/gameengine/GameLogic/SCA_IController.h
index 1b9d8fb0d2b..a52c57ab3ed 100644
--- a/source/gameengine/GameLogic/SCA_IController.h
+++ b/source/gameengine/GameLogic/SCA_IController.h
@@ -45,6 +45,7 @@ protected:
 	std::vector<class SCA_IActuator*>	m_linkedactuators;
 	unsigned int						m_statemask;
 	bool								m_justActivated;
+	bool								m_bookmark;
 public:
 	SCA_IController(SCA_IObject* gameobj,PyTypeObject* T);
 	virtual ~SCA_IController();
@@ -76,13 +77,24 @@ public:
 	{
 		m_justActivated = false;
 	}
-
+	void SetBookmark(bool bookmark)
+	{
+		m_bookmark = bookmark;
+	}
 	void Activate(SG_DList& head)
 	{
 		if (QEmpty())
 		{
-			InsertActiveQList(m_gameobj->m_activeControllers);
-			head.AddBack(&m_gameobj->m_activeControllers);
+			if (m_bookmark)
+			{
+				m_gameobj->m_activeBookmarkedControllers.QAddBack(this);
+				head.AddFront(&m_gameobj->m_activeBookmarkedControllers);
+			}
+			else
+			{
+				InsertActiveQList(m_gameobj->m_activeControllers);
+				head.AddBack(&m_gameobj->m_activeControllers);
+			}
 		}
 	}
 
diff --git a/source/gameengine/GameLogic/SCA_IObject.cpp b/source/gameengine/GameLogic/SCA_IObject.cpp
index 8962c8e8580..2b87a7c1526 100644
--- a/source/gameengine/GameLogic/SCA_IObject.cpp
+++ b/source/gameengine/GameLogic/SCA_IObject.cpp
@@ -39,13 +39,12 @@
 #endif
 
 MT_Point3 SCA_IObject::m_sDummy=MT_Point3(0,0,0);
+SG_QList SCA_IObject::m_activeBookmarkedControllers;
 
 SCA_IObject::SCA_IObject(PyTypeObject* T): CValue(T), m_initState(0), m_state(0)
 {
 	m_suspended = false;
 }
-	
-
 
 SCA_IObject::~SCA_IObject()
 {
diff --git a/source/gameengine/GameLogic/SCA_IObject.h b/source/gameengine/GameLogic/SCA_IObject.h
index 281c72ecd46..c4f346059d4 100644
--- a/source/gameengine/GameLogic/SCA_IObject.h
+++ b/source/gameengine/GameLogic/SCA_IObject.h
@@ -64,11 +64,16 @@ protected:
 	// SG_QList: Head of active actuators list on this object
 	//           Elements: SCA_IActuator
 	SG_QList			   m_activeActuators;
-	// SG_Dlist: element of objects with active controllers
+	// SG_Dlist: element of list os lists with active controllers
 	//           Head: SCA_LogicManager::m_activeControllers
 	// SG_QList: Head of active controller list on this object
 	//           Elements: SCA_IController
 	SG_QList			   m_activeControllers;
+	// SG_Dlist: element of list of lists of active controllers
+	//           Head: SCA_LogicManager::m_activeControllers
+	// SG_QList: Head of active bookmarked controller list globally
+	//           Elements: SCA_IController with bookmark option
+	static SG_QList		   m_activeBookmarkedControllers;
 
 	static class MT_Point3 m_sDummy;
 
diff --git a/source/gameengine/Ketsji/KX_StateActuator.h b/source/gameengine/Ketsji/KX_StateActuator.h
index 57303ad403f..a4191a4c5fd 100644
--- a/source/gameengine/Ketsji/KX_StateActuator.h
+++ b/source/gameengine/Ketsji/KX_StateActuator.h
@@ -33,6 +33,13 @@
 
 #include "SCA_IActuator.h"
 
+
+/*
+ * Use of SG_DList : element of actuator being deactivated
+ *                   Head: SCA_LogicManager::m_removedActuators
+ * Use of SG_QList : element of global activated state actuator list 
+ *                   Head: KX_StateActuator::m_stateActuatorHead
+ */
 class KX_StateActuator : public SCA_IActuator
 {
 	Py_Header;
@@ -46,6 +53,10 @@ class KX_StateActuator : public SCA_IActuator
 		OP_NEG,
 		OP_COUNT
 	};
+	// SG_Dlist: element of objects with active actuators, always put in front of the list
+	//           Head: SCA_LogicManager::m_activeActuators
+	// SG_QList: Head of active state actuators list globally
+	//           Elements: KX_StateActuator
 	static SG_QList	m_stateActuatorHead;
 	int				m_operation;
 	int				m_mask;
diff --git a/source/gameengine/PyDoc/GameTypes.py b/source/gameengine/PyDoc/GameTypes.py
index 3a6c62e7d23..ca02b1a2798 100644
--- a/source/gameengine/PyDoc/GameTypes.py
+++ b/source/gameengine/PyDoc/GameTypes.py
@@ -240,6 +240,10 @@ class SCA_IController(SCA_ILogicBrick):
 						- note: the sensors are not necessarily owned by the same object.
 						- note: when objects are instanced in dupligroups links may be lost from objects outside the dupligroup.
 	@type actuators: sequence supporting index/string lookups and iteration.
+	@ivar bookmark: the bookmark option.
+	                If set, the controller executes always before all other non-bookmarked controllers.
+	                - note: Order of execution between bookmarked controllers is not guaranteed.
+	@type bookmark: bool
 	"""
 #{ Deprecated
 	def getState():