{"type":"doc","content":[{"type":"paragraph","content":[{"text":"\nIn this section we are going to create a new behaviour module. This behaviour module is a simple follow target module.","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Writing the behaviour module","type":"text"}]},{"type":"paragraph","content":[{"text":"Create a new class and inherit from the base Atoms::BehaviourModule class. Define a a constructor, a destructor and a static creator function (needed by Atoms to create an instance of this module).","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"class FollowTargetModule: public Atoms::BehaviourModule\n{\n\tpublic:\n\n\t\tFollowTargetModule()\n\t\t{}\n\n\t\tvirtual ~FollowTargetModule()\n\t\t{}\n\n\t\tstatic Atoms::BehaviourModule* creator(const std::string& parameter);\n};\n\nAtoms::BehaviourModule* FollowTargetModule::creator(const std::string& parameter)\n{\n\treturn new FollowTargetModule();\n}","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"text":"For this module we'll need only a target position attribute. The attributes of the module are stored inside a MapMetadata object, you can add new attributes using the addAttribute function. Attributes should always be added inside the constructor.","type":"text"}]},{"type":"paragraph","content":[{"text":"The third attribute of the addAttribute method defines if the attribute is overridable per agent or not. In this example we'll make it overridable.","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"FollowTargetModule(): Atoms::BehaviourModule()\n{\n\tAtomsCore::Vector3Metadata targetPosition(AtomsCore::Vector3(0.0,0.0,0.0));\n\t// The last argumet specify if this attribute can be override per agent\n\taddAttribute(\"targetPosition\", &targetPosition, true);\n}","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"text":"Now we need to compute the new agent direction at each frame before the agent pose is computed. This will be done inside the initFrame method.","type":"text"}]},{"type":"paragraph","content":[{"text":"For this example we won't need to override any other method.","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"void initFrame(const std::vector& agents, Atoms::AgentGroup* agentGroup = nullptr)\n{\n}","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"text":"In the initFrame function get the targetPosition value, iterate over each agent to read the position and set their new direction.","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"void initFrame(const std::vector& agents, Atoms::AgentGroup* agentGroup = nullptr)\n{\n\t// Get the target position from the moduel attribute\n\tAtomsCore::MapMetadata& attributeMap = attributes();\n\tAtomsCore::Vector3& targetPosition = attributeMap.getTypedEntry(\"targetPosition\")->get();\n\n\t// iterate over each agent\n\tfor(Atoms::Agent* agent: agents)\n\t{\n\t\tif (!agent)\n\t\t\tcontinue;\n\t\t//get the agent position\n\t\tAtomsPtr positionPtr = agent->metadata().getTypedEntry(\"position\");\n\t\tAtomsPtr directionPtr = agent->metadata().getTypedEntry(\"direction\");\n\t\tif(!positionPtr || !directionPtr )\n\t\t\tcontinue;\n\n\t\t// compute the new direction\n\t\tdirectionPtr->set((targetPosition - positionPtr->get()).normalized()); \n\t}\n}","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"text":"The target position attribute is overridable per agent, but the code to handle it isn't there yet. When you override an attribute, a new map metadata named \"AttributeName_override\" is created. The keys of this map metadata are the agent group ids, but they will be present only when the user specifies an override from inside his 3D application.","type":"text"}]},{"type":"paragraph","content":[{"text":"In order to know if an agent has an override, please check the metadata map. If it's not there, please use the global attribute.","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"void initFrame(const std::vector& agents, Atoms::AgentGroup* agentGroup = nullptr)\n{\n\t// Get the target position from the moduel attribute\n\tAtomsCore::MapMetadata& attributeMap = attributes();\n\tAtomsCore::Vector3& targetPosition = attributeMap.getTypedEntry(\"targetPosition\")->get();\n\n\t//get the override map metadata\n\tAtomsPtr targetPositionOverride = attributeMap.getTypedEntry(\"targetPosition_override\");\n\n\n\t// iterate over each agent\n\tfor(Atoms::Agent* agent: agents)\n\t{\n\t\tif (!agent)\n\t\t\tcontinue;\n\t\t//get the agent position\n\t\tAtomsPtr positionPtr = agent->metadata().getTypedEntry(\"position\");\n\t\tAtomsPtr directionPtr = agent->metadata().getTypedEntry(\"direction\");\n\t\tif(!positionPtr || !directionPtr )\n\t\t\tcontinue;\n\n\t\tconst std::string& groupIdStr = agent->groupIdStr()->get();\n\n\t\t//check if the agent is inside the override map\n\t\tAtomsPtr overrideTargetPos = targetPositionOverride->getTypedEntry(groupIdStr);\n\t\tif (overrideTargetPos)\n\t\t{\n\t\t\t// compute the new direction\n\t\t\tdirectionPtr->set((overrideTargetPos->get() - positionPtr->get()).normalized()); \n\t\t}\n\t\telse\n\t\t{\n\t\t\t// compute the new direction\n\t\t\tdirectionPtr->set((targetPosition - positionPtr->get()).normalized()); \n\t\t}\n\t}\n}","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"text":"If you want improve the performance of the module you can add tbb to parallelize the main for loop.","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"void initFrame(const std::vector& agents, Atoms::AgentGroup* agentGroup = nullptr)\n{\n\t// Get the target position from the moduel attribute\n\tAtomsCore::MapMetadata& attributeMap = attributes();\n\tAtomsCore::Vector3& targetPosition = attributeMap.getTypedEntry(\"targetPosition\")->get();\n\n\t//get the override map metadata\n\tAtomsPtr targetPositionOverride = attributeMap.getTypedEntry(\"targetPosition_override\");\n\n\n\n\t// iterate over each agent\n AtomsUtils::parallel_for(AtomsUtils::ParallelForRange(0, agents.size()),\n [&](const AtomsUtils::ParallelForRange& r TASK_PARTITION_EXTRA_ARGS)\n {\n for (size_t i = r.begin(); i < r.end(); i++)\n\t\t{\n\t\t\tAtoms::Agent* agent = agents[i];\n\n\t\t\tif (!agent)\n\t\t\t\tcontinue;\n\t\t\t//get the agent position\n\t\t\t/* You can also access the direction ad position metadata direcly\n\t\t\tAtomsPtr& positionPtr = agent->position();\n\t\t\tAtomsPtr& directionPtr = agent->direction();\n\t\t\t*/\n\t\t\tAtomsPtr positionPtr = agent->metadata().getTypedEntry(\"position\");\n\t\t\tAtomsPtr directionPtr = agent->metadata().getTypedEntry(\"direction\");\n\t\t\tif(!positionPtr || !directionPtr )\n\t\t\t\tcontinue;\n\n\t\t\tconst std::string& groupIdStr = agent->groupIdStr()->get();\n\t\n\t\t\t//check if the agent is inside the override map\n\t\t\tAtomsPtr overrideTargetPos = targetPositionOverride->getTypedEntry(groupIdStr);\n\t\t\tif (overrideTargetPos)\n\t\t\t{\n\t\t\t\t// compute the new direction\n\t\t\t\tdirectionPtr->set((overrideTargetPos->get() - positionPtr->get()).normalized()); \n\t\t\t}\n\t\t\telse\n\t\t\t{\n\t\t\t\t// compute the new direction\n\t\t\t\tdirectionPtr->set((targetPosition - positionPtr->get()).normalized()); \n\t\t\t}\n\t\t}\n\t});\n}","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Add visual debugging options","type":"text"}]},{"type":"paragraph","content":[{"text":"Lets implement a the draw function to visually debug the direction vector. Add a std::vector m_drawLines to the class to store the lines data.","type":"text"}]},{"type":"paragraph","content":[{"text":"Inside the preDraw function you can collect the data form the agentse because it is called only if the time changes.","type":"text"}]},{"type":"paragraph","content":[{"text":"Then inside the draw function you can finally call the draw lines function to draw some lines.","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"void preDraw(Atoms::DrawContext* context, const std::vector& agents, Atoms::AgentGroup* agentGroup)\n{\n\t// The pre draw function is called only on time or attribute change,\n\t// so it's safe to collect the data from the agents here\n\tm_drawLines.resize(agents.size()*2);\n\tfor (size_t i = 0; i < agents.size(); i++) \n\t{\n\t\tAtoms::Agent* agent = agents[i];\n\t\t \n\t\t//get the agent position \n\t\tAtomsPtr positionPtr = agent->metadata().getTypedEntry(\"position\"); \n\t\tAtomsPtr directionPtr = agent->metadata().getTypedEntry(\"direction\"); \n\t\tif(!positionPtr || !directionPtr ) continue;\n\t\t\n\t\tm_drawLines[i*2] = positionPtr->get();\n\t\tm_drawLines[i*2 + 1] = positionPtr->get() + directionPtr0>get();\n\t}\n}\n\nvoid draw(Atoms::DrawContext* context, const std::vector& agents, Atoms::AgentGroup* agentGroup) \n{\n\t// the draw function is called when the dcc update the viewports\n\tcontext->lines(m_drawLines);\n}","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Register the behaviour module","type":"text"}]},{"type":"paragraph","content":[{"text":"Now the behaviour module must be added to the behaviour module factory.","type":"text"}]}]},{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"extern \"C\"\n{\n ATOMSPLUGIN_EXPORT bool initializePlugin()\n {\n AtomsUtils::Logger::info() << \"Loading atoms test plugin\";\n return true;\n }\n\n ATOMSPLUGIN_EXPORT bool uninitializePlugin()\n {\n AtomsUtils::Logger::info() << \"Unloading atoms test plugin\";\n return true;\n }\n\n ATOMSPLUGIN_EXPORT bool initializeScene()\n {\n AtomsUtils::Logger::info() << \"Loading atoms test scene plugin\";\n Atoms::BehaviourModules& moduleManager = Atoms::BehaviourModules::instance();\n moduleManager.registerBehaviourModule(\"SimpleFollowTarget\", &FollowTargetModule::creator, Atoms::BehaviourModules::kNative,true, \"MyCategory\");\n\n return true;\n }\n\n ATOMSPLUGIN_EXPORT bool uninitializeScene()\n {\n Atoms::BehaviourModules& moduleManager = Atoms::BehaviourModules::instance();\n moduleManager.deregisterBehaviourModule(\"SimpleFollowTarget\");\n return true;\n }\n\n}\n","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"layoutSection","content":[{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"heading","attrs":{"level":2},"content":[{"text":"Compile the behaviour module","type":"text"}]},{"type":"paragraph","content":[{"text":"Use this cmake file as template, change the project name and the source files and set the ATOMS_MAYA_FOLDER or ATOMS_HOUDINI_FOLDER env.","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]},{"type":"layoutColumn","attrs":{"width":50.0},"content":[{"type":"paragraph","content":[{"type":"hardBreak"}]},{"type":"codeBlock","content":[{"text":"cmake_minimum_required (VERSION 3.17)\n\nproject (\"MyAtomsPlugin\")\n\n\nif (MSVC)\ncmake_policy(SET CMP0091 NEW)\nendif()\n\nenable_language(CXX)\nset(CMAKE_CXX_STANDARD 14)\n\nadd_definitions(-DBUILD_ATOMSPLUGIN)\nadd_definitions(-DTBB_USE_DEBUG=0)\nadd_definitions(-D__TBB_LIB_NAME=tbb)\nadd_definitions(-DNOMINMAX)\nadd_definitions(-DBOOST_ALL_NO_LIB)\n\nif (UNIX)\nadd_definitions(-DLINUX)\nadd_definitions(-DPIC)\nadd_definitions(-D_FILE_OFFSET_BITS=64)\nadd_definitions(-D_GLIBCXX_USE_CXX11_ABI=0)\nadd_compile_options(-std=c++14 -ffloat-store -fvisibility=hidden -fPIC)\nendif()\n\n\nif(DEFINED ATOMS_MAYA_FOLDER)\ninclude_directories(${ATOMS_MAYA_FOLDER}/include)\nlink_directories(${ATOMS_MAYA_FOLDER}/lib/${MAYA_MAJOR_VERSION})\nset(ATOMS_CUSTOM_PLUGINS_FOLDER ${ATOMS_MAYA_FOLDER}/plugins/${MAYA_MAJOR_VERSION})\nendif()\n\nif(DEFINED ATOMS_HOUDINI_FOLDER)\ninclude_directories(${ATOMS_HOUDINI_FOLDER}/include)\nlink_directories(${ATOMS_HOUDINI_FOLDER}/lib)\nset(ATOMS_CUSTOM_PLUGINS_FOLDER ${ATOMS_HOUDINI_FOLDER}/plugins)\nendif()\n\ninclude_directories(include)\n\n\nset(SOURCES\n \"MyAtomsPlugin.cpp\")\n\nadd_library(${PROJECT_NAME} SHARED ${SOURCES})\n\nif (MSVC)\nset_property(TARGET ${PROJECT_NAME} PROPERTY\n MSVC_RUNTIME_LIBRARY MultiThreadedDLL)\nendif()\n\nset_target_properties(${PROJECT_NAME}\n PROPERTIES\n INSTALL_RPATH_USE_LINK_PATH True)\n\ntarget_link_libraries(${PROJECT_NAME}\n PUBLIC Atoms AtomsCore AtomsGraph AtomsUtils AtomsMath\n )\n\ninstall(TARGETS ${PROJECT_NAME} DESTINATION ${ATOMS_CUSTOM_PLUGINS_FOLDER})","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Use the behaviour module","type":"text"}]},{"type":"paragraph","content":[{"text":"Add to the ATOMS_PLUGINS_PATH environment variable, the folder where the plugin is located. Then the module is automatically loaded when you load atoms.","type":"text"}]},{"type":"rule"},{"type":"paragraph","content":[{"text":"Final code","type":"text"}]},{"type":"codeBlock","attrs":{"language":"c++"},"content":[{"text":"#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n#include \n\nclass FollowTargetModule : public Atoms::BehaviourModule\n{\npublic:\n\n FollowTargetModule(): Atoms::BehaviourModule()\n {\n AtomsCore::Vector3Metadata targetPosition(AtomsCore::Vector3(0.0,0.0,0.0));\n // The last argumet specify if this attribute can be override per agent\n addAttribute(\"targetPosition\", &targetPosition, true);\n }\n\n ~FollowTargetModule()\n {\n }\n\n void initFrame(const std::vector& agents, Atoms::AgentGroup* agentGroup = nullptr)\n {\n // Get the target position from the moduel attribute\n AtomsCore::MapMetadata& attributeMap = attributes();\n AtomsCore::Vector3& targetPosition = attributeMap.getTypedEntry(\"targetPosition\")->get();\n\n //get the override map metadata\n AtomsPtr targetPositionOverride = attributeMap.getTypedEntry(\"targetPosition_override\");\n\n\n\n // iterate over each agent\n AtomsUtils::parallel_for(AtomsUtils::ParallelForRange(0, agents.size()),\n [&](const AtomsUtils::ParallelForRange& r TASK_PARTITION_EXTRA_ARGS)\n {\n for (size_t i = r.begin(); i < r.end(); i++)\n {\n Atoms::Agent* agent = agents[i];\n\n if (!agent)\n continue;\n //get the agent position\n /* You can also access the direction ad position metadata direcly with\n\t\t\tAtomsPtr& positionPtr = agent->position();\n\t\t\tAtomsPtr& directionPtr = agent->direction();\n\t\t */\n AtomsPtr positionPtr = agent->metadata().getTypedEntry(\"position\");\n AtomsPtr directionPtr = agent->metadata().getTypedEntry(\"direction\");\n if(!positionPtr || !directionPtr )\n continue;\n\n //convert the groupId to a string since the map metadata use only strings as key\n const std::string& groupIdStr = agent->groupIdStr()->get();\n\n //check if the agent is inside the override map\n AtomsPtr overrideTargetPos = targetPositionOverride->getTypedEntry(groupIdStr);\n if (overrideTargetPos)\n {\n // compute the new direction\n directionPtr->set((overrideTargetPos->get() - positionPtr->get()).normalized());\n }\n else\n {\n // compute the new direction\n directionPtr->set((targetPosition - positionPtr->get()).normalized());\n }\n }\n });\n }\n\n void preDraw(Atoms::DrawContext* context, const std::vector& agents, Atoms::AgentGroup* agentGroup)\n {\n // The pre draw function is called only when the time is changed or some attribute is changed so\n // we can collect the data from the agents here\n m_drawLines.resize(agents.size()*2);\n for (size_t i = 0; i < agents.size(); i++)\n {\n Atoms::Agent* agent = agents[i];\n\n //get the agent position\n AtomsPtr positionPtr = agent->metadata().getTypedEntry(\"position\");\n AtomsPtr directionPtr = agent->metadata().getTypedEntry(\"direction\");\n if(!positionPtr || !directionPtr ) continue;\n\n m_drawLines[i*2] = positionPtr->get();\n m_drawLines[i*2 + 1] = positionPtr->get() + directionPtr->get();\n }\n }\n\n void draw(Atoms::DrawContext* context, const std::vector& agents, Atoms::AgentGroup* agentGroup)\n {\n // the draw function is called when the dcc update the viewports\n context->lines(m_drawLines);\n }\n\n static Atoms::BehaviourModule* creator(const std::string& parameter);\n\nprivate:\n\n std::vector m_drawLines;\n};\n\nAtoms::BehaviourModule* FollowTargetModule::creator(const std::string& parameter)\n{\n return new FollowTargetModule();\n}\n\nextern \"C\"\n{\n ATOMSPLUGIN_EXPORT bool initializePlugin()\n {\n AtomsUtils::Logger::info() << \"Loading atoms plugin\";\n return true;\n }\n\n ATOMSPLUGIN_EXPORT bool uninitializePlugin()\n {\n AtomsUtils::Logger::info() << \"Unloading atoms plugin\";\n return true;\n }\n\n ATOMSPLUGIN_EXPORT bool initializeScene()\n {\n AtomsUtils::Logger::info() << \"Loading atoms scene plugin\";\n Atoms::BehaviourModules& moduleManager = Atoms::BehaviourModules::instance();\n moduleManager.registerBehaviourModule(\"SimpleFollowTarget\", &FollowTargetModule::creator, Atoms::BehaviourModules::kNative,true, \"MyCategory\");\n\n return true;\n }\n\n ATOMSPLUGIN_EXPORT bool uninitializeScene()\n {\n Atoms::BehaviourModules& moduleManager = Atoms::BehaviourModules::instance();\n moduleManager.deregisterBehaviourModule(\"SimpleFollowTarget\");\n return true;\n }\n\n}\n","type":"text"}]},{"type":"paragraph","content":[{"type":"hardBreak"}]}],"version":1}