{"id":22217057,"url":"https://github.com/kestrelm/creature_cocos2dx","last_synced_at":"2025-08-02T01:11:51.898Z","repository":{"id":31900427,"uuid":"35469377","full_name":"kestrelm/Creature_Cocos2DX","owner":"kestrelm","description":"Cocos2d-x Runtimes for Creature","archived":false,"fork":false,"pushed_at":"2019-06-21T06:52:23.000Z","size":2119,"stargazers_count":10,"open_issues_count":0,"forks_count":5,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-04T02:51:10.966Z","etag":null,"topics":["2d","android","animation","bones","cocos2d-x","cocos2dx","creature","cutout","deformation","engine","ffd","gamedev","indie","mesh","plugin","puppet","runtime","skeletal","skinning","spine"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kestrelm.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-12T05:48:10.000Z","updated_at":"2022-02-11T05:41:04.000Z","dependencies_parsed_at":"2022-08-26T10:01:36.983Z","dependency_job_id":null,"html_url":"https://github.com/kestrelm/Creature_Cocos2DX","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kestrelm/Creature_Cocos2DX","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestrelm%2FCreature_Cocos2DX","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestrelm%2FCreature_Cocos2DX/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestrelm%2FCreature_Cocos2DX/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestrelm%2FCreature_Cocos2DX/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kestrelm","download_url":"https://codeload.github.com/kestrelm/Creature_Cocos2DX/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kestrelm%2FCreature_Cocos2DX/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266240896,"owners_count":23898062,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2d","android","animation","bones","cocos2d-x","cocos2dx","creature","cutout","deformation","engine","ffd","gamedev","indie","mesh","plugin","puppet","runtime","skeletal","skinning","spine"],"created_at":"2024-12-02T22:14:53.937Z","updated_at":"2025-07-21T04:32:48.861Z","avatar_url":"https://github.com/kestrelm.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Creature-Runtimes\n\nFor more information on how to use the runtimes, please head over to this [site](http://www.kestrelmoon.com/creaturedocs/Game_Engine_Runtimes_And_Integration/Runtimes_Introduction.html)\n\n## Overview\nThis document describes how to use the Cocos2d-x runtimes. The language of the runtimes is in C++. There are 2 types of formats to read in, the JSON fully featured format or the much more performant + compact CreaturePack format.\n\n## JSON\n\n### Libaries Needed to compile\nAlong with the core runtime files, the following libraries are also included:\n\n- **gason** (Include the Header and also compile the single gason.cpp source)\n\n- **glm** (Header only so make sure your include paths are setup for it)\n\nMake sure to include these 2 libraries in source form in your project.\n\n\n### Header Includes\nThe following headers need to be included:\n\n\t#include \"MeshBone.h\"\n\t#include \"CreatureRenderer.h\"\n\n### Loading and Initialization\nLet us assume we have an exported dragon animation file called **dragonTest.json**. We also have its corresponding texture atlas called **character-dragon.png**.\nWe start off by first loading the file assets:\n\n    auto filename = CCFileUtils::getInstance()-\u003efullPathForFilename(\"dragonTest.json\");\n    auto texture_filename = CCFileUtils::getInstance()-\u003efullPathForFilename(\"character-dragon.png\");\n    \n    CreatureModule::CreatureLoadDataPacket json_data;\n    CreatureModule::LoadCreatureJSONData(filename, json_data);\n\nThe above will load the **JSON** data from disk and into memory. Next, let us create the actual objects that can make use of these loaded assets:\n\n    auto cur_creature = std::shared_ptr\u003cCreatureModule::Creature\u003e(new CreatureModule::Creature(json_data));\n    \n    creature_manager = new CreatureModule::CreatureManager(cur_creature);\n    creature_manager-\u003eCreateAnimation(json_data, \"default\");\n    creature_manager-\u003eCreateAnimation(json_data, \"second\");    \nIn the example above, the **JSON** file has 2 animation clips: **default** and **second**. Hence, we will need to create 2 animations from the **creature_manager** object to make them available for playback.    \n\nNow that we are done loading, we can set the active animation for playback:\n\n\tcreature_manager-\u003eSetActiveAnimationName(\"default\");\n\nThis sets **default** as the currently active animation.\nWe will now go ahead and create the object to render the character animation:\n\n    auto creature_renderer = CreatureRenderer::Renderer::create(\n    \tcreature_manager,CCTextureCache::getInstance()-\u003eaddImage(\"character-dragon.png\"));\n\nThis creates a creature renderer with our texture atlas image file. Once that is done, we can go ahead and set some playback and rendering properties:\n\n    creature_manager-\u003eSetIsPlaying(true);\n    creature_manager-\u003eSetShouldLoop(true);\n    creature_manager-\u003eSetMirrorY(true);\n    creature_renderer-\u003esetColor(cocos2d::Color3B(255, 255, 255));\n\n    Size visibleSize = Director::getInstance()-\u003egetVisibleSize();\n    Vec2 origin = Director::getInstance()-\u003egetVisibleOrigin();\n    creature_renderer-\u003esetScale(30.0);\n    creature_renderer-\u003esetPosition(Vec2(visibleSize.width/2 + origin.x, visibleSize.height/2 + origin.y));\n    \n\nFinally, we add the object to the scene:\n\n    this-\u003eaddChild(creature_renderer, 1);\n\nThat concludes the basic instructions on how to integrate your character into Cocox2dX!\n\n### Complete Code Sample\nHere is the complete code layout. Most the the code is generated from the default Cocos2dX project starter template. Pay attention to the method **loadModel()** which does most of the work:\n\n\t#include \"HelloWorldScene.h\"\n\t#include \"MeshBone.h\"\n\t#include \"CreatureRenderer.h\"\n\n\tUSING_NS_CC;\n\n\tScene* HelloWorld::createScene()\n\t{\n   \t\t // 'scene' is an autorelease object\n\t    auto scene = Scene::create();\n    \n\t    // 'layer' is an autorelease object\n\t    auto layer = HelloWorld::create();\n\n   \t\t // add layer as a child to scene\n\t    scene-\u003eaddChild(layer);\n\n\t    // return the scene\n   \t\t return scene;\n\t}\n\n\tvoid HelloWorld::loadModel()\n\t{\n\t\t// The actual code that loads the character animation data\n\t    auto filename = CCFileUtils::getInstance()-\u003efullPathForFilename(\"dragonTest.json\");\n\t    auto texture_filename = CCFileUtils::getInstance()-\u003efullPathForFilename(\"character-dragon.png\");\n    \n\t    CreatureModule::CreatureLoadDataPacket json_data;\n\t    CreatureModule::LoadCreatureJSONData(filename, json_data);\n    \n\t    auto cur_creature = std::shared_ptr\u003cCreatureModule::Creature\u003e(new CreatureModule::Creature(json_data));\n    \n\t    creature_manager = new CreatureModule::CreatureManager(cur_creature);\n\t    creature_manager-\u003eCreateAnimation(json_data, \"default\");\n    \tcreature_manager-\u003eCreateAnimation(json_data, \"second\");\n    \n\t    creature_manager-\u003eSetActiveAnimationName(\"default\");\n    \n\t    auto creature_renderer = CreatureRenderer::Renderer::create(creature_manager,                                                             \t\t\t CCTextureCache::getInstance()-\u003eaddImage(\"character-dragon.png\"));\n\t    creature_manager-\u003eSetIsPlaying(true);\n\t    creature_manager-\u003eSetShouldLoop(true);\n\t    creature_manager-\u003eSetMirrorY(true);\n\t    creature_renderer-\u003esetColor(cocos2d::Color3B(255, 255, 255));\n\t    creature_renderer-\u003eSetDebugDraw(false);\n    \n    \n\t    Size visibleSize = Director::getInstance()-\u003egetVisibleSize();\n\t    Vec2 origin = Director::getInstance()-\u003egetVisibleOrigin();\n\t    creature_renderer-\u003esetScale(30.0);\n\t    creature_renderer-\u003esetPosition(Vec2(visibleSize.width/2 + origin.x, visibleSize.height/2 + origin.y));\n\n\t    this-\u003eaddChild(creature_renderer, 1);\n\t\tscheduleUpdate();\n\t}\n\n\t\t// on \"init\" you need to initialize your instance\n\t\tbool HelloWorld::init()\n\t\t{\n\t\t    //////////////////////////////\n\t\t    // 1. super init first\n\t\t    if ( !Layer::init() )\n\t   \t\t {\n\t   \t   \t  return false;\n\t\t    }\n    \n\t\t    Size visibleSize = Director::getInstance()-\u003egetVisibleSize();\n\t   \t\t Vec2 origin = Director::getInstance()-\u003egetVisibleOrigin();\n\n\t\t    /////////////////////////////\n\t\t\t // 2. add a menu item with \"X\" image, which is clicked to quit the program\n\t   \t\t //    you may modify it.\n\n\t\t    // add a \"close\" icon to exit the progress. it's an autorelease object\n\t\t    auto closeItem = MenuItemImage::create(\n                                           \"CloseNormal.png\",\n                                           \"CloseSelected.png\",\n                                           CC_CALLBACK_1(HelloWorld::menuCloseCallback, this));\n    \n\t\t\tcloseItem-\u003esetPosition(Vec2(origin.x + visibleSize.width - closeItem-\t\u003egetContentSize().width/2 ,\n                                origin.y + closeItem-\u003egetContentSize().height/2));\n\n\t\t    // create menu, it's an autorelease object\n\t\t    auto menu = Menu::create(closeItem, NULL);\n\t\t    menu-\u003esetPosition(Vec2::ZERO);\n\t\t    this-\u003eaddChild(menu, 1);\n\n\t\t    /////////////////////////////\n\t\t    // 3. add your codes below...\n\n\t\t    // add a label shows \"Hello World\"\n\t\t    // create and initialize a label\n    \n\t\t    auto label = LabelTTF::create(\"Hello World\", \"Arial\", 24);\n    \n\t\t    // position the label on the center of the screen\n\t\t    label-\u003esetPosition(Vec2(origin.x + visibleSize.width/2,\n                            origin.y + visibleSize.height - label-\u003egetContentSize().height));\n\n\t\t    // add the label as a child to this layer\n\t\t    this-\u003eaddChild(label, 1);\n\n\t\t    // add \"HelloWorld\" splash screen\"\n\t\t    auto sprite = Sprite::create(\"HelloWorld.png\");\n\n\t\t    // position the sprite on the center of the screen\n\t\t    sprite-\u003esetPosition(Vec2(visibleSize.width/2 + origin.x, visibleSize.height/2 + origin.y));\n\n\t\t    // add the sprite as a child to this layer\n\t\t    this-\u003eaddChild(sprite, 0);\n    \n    \t\t// Load your character\n\t\t    loadModel();\n    \n\t   \t\treturn true;\n\t\t}\n\n\tvoid HelloWorld::menuCloseCallback(Ref* pSender)\n\t{\n\t    Director::getInstance()-\u003eend();\n\t}\n\t\n### SkinSwapping\n\nYou can enable and use SkinSwapping in the runtimes by first loading the metadata into the **CreatureRenderer**, setting the SkinSwap you want and then activating it:\n\n    auto meta_filename = CCFileUtils::getInstance()-\u003efullPathForFilename(\"swapGirl.mdata\");\n    creature_renderer-\u003eloadMetaData(meta_filename);\n    creature_renderer-\u003esetSkinSwap(\"cape\");\n    creature_renderer-\u003esetUseSkinSwap(true);\n    \nSkinSwapping requires the **metadata JSON**(.mdata) to be loaded and included in your project.    \n\n### Custom Time/Frame Range\n\nYou can set custom time/frame ranges for the currently active animation. Say you wanted to limit the playback to the frame range of **10 to 20**, you would do the following:\n\n    creature_manager-\u003eSetUseCustomTimeRange(true);\n    creature_manager-\u003eSetCustomTimeRange(10, 20);\n\n### Animation Blending\nYou can blend between 2 animation clips by doing the following:\n\n    creature_manager-\u003eSetBlending(true);\n    creature_manager-\u003eSetBlendingAnimations(\"default\", \"second\");\n    creature_manager-\u003eSetBlendingFactor(0.5); // 0 to 1 blends between the 2 clips\n    \n### Smooth Transitions with Auto Blending\nIf you want to smoothly transition from one animation state to the next, you can use the Auto Blending feature in the runtimes.\n\nTo enable Auto Blending, first do:\n\n\tcreature_manager-\u003eSetAutoBlending(true);\n\nafter you have added all animations into your creature manager object.\n\nTo use Auto Blending, a single call to:\n\n\tcreature_manager-\u003eAutoBlendTo(NEW_ANIMATION_NAME, 0.1f);\n\nwill result in the character smoothly transitioning to the target animation called NEW_ANIMATION_NAME. The second parameter determines the time delta of the transition, with a range of 0.0 to 1.0.\n\n### Overriding/Modifying Bone Positions\nSometimes you need to modify the bone positions of the character directly. For example, you might want the positions of the bones to follow a number of rigid bodies connected with springs/joints for ragdoll physics. In the cases where you need to set bone positions for your own custom requirements, you should do the following. First, write your custom bone override method. Here is an example that displaces the bones in y by some amount:\n\n\t// This is an example of how you can use a callback function to modify the position of the bones\n\t// on your character. In this example, we will displace all the bones by a fixed amount in y.\n\tvoid\n\tHelloWorld::bonesModifyCallback(std::unordered_map\u003cstd::string, meshBone *\u003e\u0026 bones_map)\n\t{\n\t    for(auto\u0026 bone_data : bones_map)\n\t    {\n\t        auto cur_bone = bone_data.second;\n\t        auto cur_start_pos = cur_bone-\u003egetWorldStartPt();\n\t        auto cur_end_pos = cur_bone-\u003egetWorldEndPt();\n        \n\t        cur_start_pos.y -= 5;\n\t        cur_end_pos.y -= 5;\n        \n\t        cur_bone-\u003esetWorldStartPt(cur_start_pos);\n\t        cur_bone-\u003esetWorldEndPt(cur_end_pos);\n\t    }\n\t}\n\nYou will also need to tell the **CreatureManager** to use your custom bone modify callback like this:\n\n    // Example of how to register a callback function to modify the bones\n    std::function\u003cvoid (std::unordered_map\u003cstd::string, meshBone *\u003e\u0026) \u003e cur_callback =\n        std::bind(\u0026HelloWorld::bonesModifyCallback, this, std::placeholders::_1);\n    creature_manager_2-\u003eSetBonesOverrideCallback(cur_callback);\n\n### Character Instancing and Memory\nIf you need to instance multiple copies of a character(for example 2 dragons), you should create your animations like this instead:\n\n    // Create and load the animations\n    auto new_animation_1 = std::shared_ptr\u003cCreatureModule::CreatureAnimation\u003e(\n                                                                            new CreatureModule::CreatureAnimation(json_data,\n                                                                                                  \"default\"));\n\n    auto new_animation_2 = std::shared_ptr\u003cCreatureModule::CreatureAnimation\u003e(\n                                                                              new CreatureModule::CreatureAnimation(json_data,\n                                                                                                                    \"pose2\"));\n\n\nYou should then proceed to you create a new **Creature** object, a new **CreatureManager** object and a new **CreatureRenderer** object. You will add the created animations into your newly created **CreatureManager** object like this:\n\n    // Second creature instancing example. This shows you how to load a second creature.\n    // Because both the first and second creature share animation data, you end up\n    // saving memory.\n    auto creature_2 = std::shared_ptr\u003cCreatureModule::Creature\u003e(new CreatureModule::Creature(json_data));\n\n    CreatureModule::CreatureManager * creature_manager_2 = new CreatureModule::CreatureManager(creature_2);\n    creature_manager_2-\u003eAddAnimation(new_animation_1);\n    creature_manager_2-\u003eAddAnimation(new_animation_2);\n    creature_manager_2-\u003eSetActiveAnimationName(\"pose2\");\n    creature_manager_2-\u003eSetIsPlaying(true);\n    creature_manager_2-\u003eSetUseCustomTimeRange(true);\n    creature_manager_2-\u003eSetCustomTimeRange(10, 60);\n    \n    auto creature_renderer_2 = CreatureRenderer::Renderer::create(creature_manager_2,\n                                                                 CCTextureCache::getInstance()-\u003eaddImage(\"character-dragon.png\"));\n    creature_renderer_2-\u003esetColor(cocos2d::Color3B(255, 255, 255));\n    creature_renderer_2-\u003esetScale(30.0);\n    creature_renderer_2-\u003esetPosition(Vec2(visibleSize.width/2 + origin.x, visibleSize.height/2 + origin.y - 200));\n    \n    this-\u003eaddChild(creature_renderer_2, 1);\n\n\nThe difference between this example and the previous is that the animations are first created, then added into their respective **CreatureManagers**. This means the memory allocated for the animations(the most expensive) are stored in a standard location. Multiple **CreatureManager** objects will add animations from a common pool of **CreatureAnimation** objects.\n\n### Speeding up Playback Performance with Point Caches\nIf you want to increase the speed of the playback animations and not pay the penalty for the posing engine, you can enable point caches on specific animations.\n\nPoint caching essentially stores away the vertices of the animation, allowing the playback to bypass the posing engine. Character rigs with very complex skeletons and deformations benefit greatly from point caching.\n\nTo enable point caching on a specific animation, do this:\n\t\n\tmy_creature_manager-\u003eMakePointCache(\"myAnimationName\");\n\nThat is all that is required to create the cache. Remember that the cache is specific to the animation, not character. This means that if you have instanced multiple characters, you only pay the cost of a single cache for that animation. This results in both **memory savings and playback performance speedups.**\n\n## Creature Pack\n\nThere is a alternative, lightweight plugin called the **CreaturePack** runtime designed for high performance playback of lots of characters. If you require high performance playback together with small binary file sizes but do not require in game bone manipulation, you might want to consider using the **Creature Pack** file format.\n\n### Required Files\n\nPlease add these files from the runtimes folder into your project:\n\n- CreaturePackRenderer.cpp\n- CreaturePackRenderer.h\n- CreaturePackModule.hpp\n- mp.h\n- mp.cpp\n\n### Usage\n\nBelow is a sample of how to create a **CreaturePackLoader** and then instantiate a new **CreaturePackRenderer** object.\n\nFirst, put in the the required include headers:\n\n\t#include \"CreaturePackModule.hpp\"\n\t#include \"CreaturePackRenderer.h\"\n\nNext, fill in the code below to use the **CreaturePack** runtime:\n\n\t// CreaturePack Demo, shows you how to load a Creature Pack character in cocos2d-x\n\n\t// First, create the CreaturePackLoader\n\tauto packFilename = CCFileUtils::getInstance()-\u003efullPathForFilename(\"testPack.creature_pack\");\n\tpackLoader = CreaturePackRenderer::createPackLoader(packFilename);\n\n\t// Now create the renderer for CreaturePack\n\tauto packRenderer =\n\t\tCreaturePackRenderer::Renderer::create(\n\t\t\tpackLoader,\n\t\t\tCCTextureCache::getInstance()-\u003eaddImage(\"testPack.png\"));\n\tpackRenderer-\u003esetScale(120.0f);\n\tpackRenderer-\u003esetPosition(Vec2(visibleSize.width / 2 + origin.x, visibleSize.height / 2 + origin.y));\n\n\tthis-\u003eaddChild(packRenderer, 1);\n\n\t// Set Animation settings\n\tauto playerObj = packRenderer-\u003egetPlayerObj();\n\tplayerObj-\u003eblendToAnimation(\"default\", 0.2f);\n\tplayerObj-\u003eisLooping = true;\n\tplayerObj-\u003eisPlaying = true;\n\tpackRenderer-\u003esetPlaybackSpeed(30.0f);\n\t\nRemember, you should **share CreaturePackLoader** objects between multiple **Renderer** objects if they are all sourced from the same asset. This saves load time and memory.\n\t\n### Important Functions to know about\n\nMost of the core functionality of **CreaturePack** lives on the **CreaturePackPlayer** object. You can get an instance of this from the **CreaturePackRenderer::Renderer** object via the **getPlayerObj()** method.\n\nOnce you have a reference to it, you can manipulate playback on it by calling the following methods or adjusting certain attributes:\n\n- **blendToAnimation(nameIn, blendDelta)** Smoothly blends between 2 animation clips\n\n- **blendToAnimation(nameIn)** Sets the active animation without blending\n\n- **getRunTime()** Returns the current time/frame of the animation\n\n- **isLoopin** This is a property you can directly set. Determines whether to loop the animation or not\n\n- **isPlaying** A boolean property you can directly set. Determines whether the animation is playing or not.\n\n\n## License\nThe **Creature Runtimes** operate under 2 License types depending on whether you own a Licensed copy of [Creature](https://creature.kestrelmoon.com) or not.\n- **People who own a licensed copy of Creature:** You use the standard **Creature License** included with the runtime code. **TLDR:** You are free to publish/modify/sell your product with the Creature runtimes without needing to state you are using the runtimes/put the copyright notice in your code/app. If you already have been using the Creature runtimes as a licensed owner of Creature, nothing changes :)\n\n- **Everyone else:** The runtimes are released under the very permissive [**Apache License**](https://choosealicense.com/licenses/apache-2.0/) :)\n\n***Both Licenses allow for private use and do not require any disclosure of your source code.***\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkestrelm%2Fcreature_cocos2dx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkestrelm%2Fcreature_cocos2dx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkestrelm%2Fcreature_cocos2dx/lists"}