{"_id":"547b1c9c4366a708001b3b52","version":{"_id":"5463e333447e0a100024a08a","project":"5463e333447e0a100024a087","__v":6,"createdAt":"2014-11-12T22:46:11.486Z","releaseDate":"2014-11-12T22:46:11.486Z","categories":["5463e333447e0a100024a08b","54645c365871e90800f50151","547b1c5a4366a708001b3b50","547b1cdf4366a708001b3b5a","54e3bef8464a9c3700f7ca67","54ec651d7ab3172d00c01ab7"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"5463e333447e0a100024a08b","project":"5463e333447e0a100024a087","pages":["5463e334447e0a100024a08d","54646a285871e90800f50174","54667e7af2b6390800dfd82a","54679c8c98b6840800268982","54679d8498b6840800268987","546a2ed0394c861a00c3a413","546b6a4862515a14007ebbba","547b1c2e7eec0f080099e1dd","55d33d90b9ef4435006dec70","56570c764d1c720d001f51bb"],"version":"5463e333447e0a100024a08a","__v":10,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-11-12T22:46:11.951Z","from_sync":false,"order":1,"slug":"documentation","title":"Documentation"},"project":"5463e333447e0a100024a087","user":"54639d06447e0a1000249f7f","__v":24,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-11-30T13:33:16.865Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"basic_auth":false,"results":{"codes":[]},"try":true,"auth":"never","params":[],"url":""},"isReference":false,"order":12,"body":"Cocos2d-x has supported 3D since v3.1 for rendering 3D objects but to be able to use every 3D feature use Cocos2d-x v3.3 or newer. Cocos2d-JS doesn't support 3D but when it does this page will be updated. 3D support is slowly being added to Cocos so if a feature doesn't exist ATM it most likely will soon.\n\nCocos uses the right handed coordinate system for cartesian coordinates.\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/TCIRwzpwR8637u1A7JUw_left_right_hand.gif\",\n        \"left_right_hand.gif\",\n        \"379\",\n        \"285\",\n        \"#ae8368\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nThere is nothing to setup to use 3D, as long as you have a project generated your good to go.\n\n##**Supported 3D Objects**\n\nThe following object types are supported:\n  * Wavefront object **.obj**\n  * Cocos2d-x 3D object **.c3b** and **.c3t**\n\nThe difference between **.c3b** and **.c3t** is **.c3b** is in binary and **.c3t** is in text. **.c3b** is recommended for production as it is faster but **.c3t** is better for debugging and testing.\n\nNote: *When using animations you must use **.c3b** or **.c3t** as **.obj** doesn't support animations*\n\n##**3D Tools** - tools to use for creating 3D objects\n\nAutodesk Maya - paid\nAutodesk 3DS Max - paid\nBlender - free\n\nMost 3D tools allow you to export models to **.obj** or **.fbx**. Thought **.fbx** isn't supported in Cocos2d-x it can be converted using the provided converter.\n\nThe converter is located at **Cocos2d-xRoot/tools/fbx-conv/mac** for Mac computers and **Cocos2d-xRoot/tools/fbx-conv/win** for Windows computers.\n\nProcess of converting a **.fbx** file to **.c3b/.c3t**:\n  * Open Terminal\n  * Change directory to the one stated above\n  * ./fbx-conv -a input.fbx file\n\nThe output file(s) are located wherever the input file is.\n\n  * -?: show help - *./fbx-conv -? input.fbx file*\n  * -a: export both text and binary format - *./fbx-conv -a input.fbx file*\n  * -b: export binary format - *./fbx-conv -b input.fbx file*\n  * -t: export text format - *./fbx-conv -t input.fbx file*\n\n##**Sprite3D** - a three-dimensional object\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Sprite3D *sprite = Sprite3D::create( \\\"3D object filepath\\\" );\\n\\nsprite->setTexture( \\\"3D objects texture filepath\\\" );\\n// set the objects position in 3D space\\nsprite->setPosition3D( Vec3( origin.x + visibleSize.width / 2, origin.y + visibleSize.height / 2, 0 ) );\\n\\n// set the objects rotation in 3D space\\nsprite->setRotation3D( Vec3( 30, 200, -90 ) );\\n\\nthis->addChild( sprite );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    }\n  ]\n}\n[/block]\nNote: *If the object appears small then change the scale like you would with any other node or modify the z position when using **setPosition3D***\n\n##**Sprite3D Animation** - a three-dimensional objects animation can be run\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Sprite3D *sprite = Sprite3D::create( \\\"3D object filepath\\\" );\\n/******\\nset the 3D sprite's properties such as texture and position\\n******/\\nthis->addChild( sprite );\\n\\n// load the animation from the 3D object\\nAnimation3D *animation = Animation3D::create( \\\"3D object filepath\\\" );\\n// check if the animation exists\\nif ( animation )\\n{\\n  // create the animation for the 3D object (Animation3D *, animationStartTime, animationEndTime)\\n  Animate3D *animate = Animate3D::create( animation, 0, 5 );\\n  // speed at which the animation is run (default is 1)\\n  animate->setSpeed( 2 );\\n  // run the animation, doesn't have to be in a RepeatForever action\\n  sprite->runAction( RepeatForever::create( animate ) );\\n}\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    }\n  ]\n}\n[/block]\nNote: *The start and end time for Animate3D doesn't affect its speed but what point in the animation it starts and ends. If the animation is a total of 3 seconds and the start time is 0 and the end time is 5 then the entire animation will be played. If the animation is a total of 3 seconds and the start time is 1.5 and the end time is 3 then the last half of the animation will play.*\n\nNote: *The start and end time for Animate3D are optional.*\n\nNote: ***Animate3D *animate = Animate3D::createWithFrames( animation, 0, 20 );** is an alternative to allow you to create an animation be specifying the start and end frames*\n\n##**Camera** - the camera is the players point of view\n\nBy default Cocos creates a camera as that is what is used to see the game world. But if you want to create a custom camera which faces a certain way for example it is easy to do so.\n\nThere are 2 different types of cameras, perspective and orthographic:\n  *  Perspective camera takes into consideration distance hence objects further away form the camera look smaller\n  * Orthographic camera doesn't take into consideration distance hence objects further away look the same size if they were nearer the camera\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/t2z2Um7DQkaFx2G97zM8_IC15161.jpg\",\n        \"IC15161.jpg\",\n        \"477\",\n        \"201\",\n        \"#820877\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// persective camera creation\\nCamera *camera = Camera::createPerspective( fieldOfView, screenRatio, nearClippingPlane, farClippingPlane );\\n// or\\n// orthographic camera creation\\nCamera *camera = Camera::createOrthographic( screenWidth, screenHeight, nearClippingPlane, farClippingPlane );\\n\\n// set parameters for camera\\ncamera->setPosition3D( cameraPosition );\\ncamera->lookAt( pointToLookAt, whichWayIsUp );\\n\\nthis->addChild( camera );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Camera Code Format\"\n    },\n    {\n      \"code\": \"// perspective camera creation\\nCamera *camera = Camera::createPerspective( 60, ( GLfloat ) visibleSize.width / visibleSize.height, 1, 1000 );\\n// or\\n// orthographic camera creation\\nCamera *camera = Camera::createOrthographic( visibleSize.width, visibleSize.height, nearClippingPlane, farClippingPlane );\\n\\n// set parameters for camera\\ncamera->setPosition3D( Vec3( 0, 0, 300 ) );\\ncamera->lookAt( Vec3( 0, 0, 0 ), Vec3( 0, 1, 0 ) );\\n\\nthis->addChild( camera ); //add camera to the scene\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    }\n  ]\n}\n[/block]\nNote: *The camera isn't a physical entity/object aka it can't be seen but is still very important in 3D game development.*\n\n##**Lighting** - lighting is used to change the atmosphere and tone of the scene\n\nThere are 4 different lighting techniques:\n  * Ambient lighting - overall illumination that doesn't originate from a particular point\n  * Directional lighting - have colour and direction but no origin/position\n  * Point lighting - have colour and position but they have no direction as they emit light in every direction\n  * Spot lighting - have colour, direction, position/origin and emit in a cone shape\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/UC8p1vGYQLSRKjYtMDO4_lights.png\",\n        \"lights.png\",\n        \"369\",\n        \"109\",\n        \"#b8a830\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"AmbientLight *ambientLight = AmbientLight::create( lightColour );\\nthis->addChild( ambientLight );\\n\\nDirectionLight *directionLight = DirectionLight::create( lightDirection, lightColour );\\nthis->addChild( directionLight );\\n\\nPointLight *pointLight = PointLight::create( lightPosition, lightColour, lightRange );\\nthis->addChild( pointLight );\\n\\nSpotLight *spotLight = SpotLight::create( lightDirection, lightPosition, lightColour, lightConeInnerAngle, lightConeOuterAngle, lightRange );\\nthis->addChild( spotLight );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Lighting Code Format\"\n    },\n    {\n      \"code\": \"AmbientLight *ambientLight = AmbientLight::create( Color3B::YELLOW );\\nthis->addChild( ambientLight );\\n\\nDirectionLight *directionLight = DirectionLight::create( Vec3( -1.0f, -1.0f, 0.0f ), Color3B::RED );\\nthis->addChild( directionLight );\\n\\nPointLight *pointLight = PointLight::create( Vec3( 0.0f, 0.0f, 0.0f ), Color3B::RED, 10000.0f );\\nthis->addChild( pointLight );\\n\\nSpotLight *spotLight = SpotLight::create( Vec3( -1.0f, -1.0f, 0.0f ), Vec3( 0.0f, 0.0f, 0.0f ), Color3B::RED, 0.0, 0.5, 10000.0f );\\nthis->addChild( spotLight );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    }\n  ]\n}\n[/block]\n##**Billboarding** - technique used to make an object always face the camera\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/pXA0mz3wQ06uoWyj9KPQ_clouds.jpg\",\n        \"clouds.jpg\",\n        \"500\",\n        \"689\",\n        \"#174888\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"BillBoard *billboard = BillBoard::create( imageFilepath, billboardingMode );\\n\\nbillboard->setPosition3D( position );\\nbillboard->setBlendFunc( blendingFunction );\\n\\nthis->addChild( billboard );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Billboarding Code Format\"\n    },\n    {\n      \"code\": \"// BillBoard::Mode::VIEW_PLANE_ORIENTED or BillBoard::Mode::VIEW_POINT_ORIENTED\\nBillBoard *billboard = BillBoard::create( \\\"Image.png\\\", BillBoard::Mode::VIEW_PLANE_ORIENTED );\\n\\nbillboard->setPosition3D( Vec3 ( 400.0f, 200.0f, 300.0f ) );\\n// BlendFunc::ALPHA_NON_PREMULTIPLIED or BlendFunc::ALPHA_PREMULTIPLIED\\nbillboard->setBlendFunc( BlendFunc::ALPHA_NON_PREMULTIPLIED );\\n\\nthis->addChild( billboard );\",\n      \"language\": \"cplusplus\",\n      \"name\": \"Cocos2d-x C++\"\n    }\n  ]\n}\n[/block]","excerpt":"This page will cover the 3D features that Cocos2d-x offers.","slug":"3d","type":"basic","title":"3D"}

3D

This page will cover the 3D features that Cocos2d-x offers.

Cocos2d-x has supported 3D since v3.1 for rendering 3D objects but to be able to use every 3D feature use Cocos2d-x v3.3 or newer. Cocos2d-JS doesn't support 3D but when it does this page will be updated. 3D support is slowly being added to Cocos so if a feature doesn't exist ATM it most likely will soon. Cocos uses the right handed coordinate system for cartesian coordinates. [block:image] { "images": [ { "image": [ "https://files.readme.io/TCIRwzpwR8637u1A7JUw_left_right_hand.gif", "left_right_hand.gif", "379", "285", "#ae8368", "" ] } ] } [/block] There is nothing to setup to use 3D, as long as you have a project generated your good to go. ##**Supported 3D Objects** The following object types are supported: * Wavefront object **.obj** * Cocos2d-x 3D object **.c3b** and **.c3t** The difference between **.c3b** and **.c3t** is **.c3b** is in binary and **.c3t** is in text. **.c3b** is recommended for production as it is faster but **.c3t** is better for debugging and testing. Note: *When using animations you must use **.c3b** or **.c3t** as **.obj** doesn't support animations* ##**3D Tools** - tools to use for creating 3D objects Autodesk Maya - paid Autodesk 3DS Max - paid Blender - free Most 3D tools allow you to export models to **.obj** or **.fbx**. Thought **.fbx** isn't supported in Cocos2d-x it can be converted using the provided converter. The converter is located at **Cocos2d-xRoot/tools/fbx-conv/mac** for Mac computers and **Cocos2d-xRoot/tools/fbx-conv/win** for Windows computers. Process of converting a **.fbx** file to **.c3b/.c3t**: * Open Terminal * Change directory to the one stated above * ./fbx-conv -a input.fbx file The output file(s) are located wherever the input file is. * -?: show help - *./fbx-conv -? input.fbx file* * -a: export both text and binary format - *./fbx-conv -a input.fbx file* * -b: export binary format - *./fbx-conv -b input.fbx file* * -t: export text format - *./fbx-conv -t input.fbx file* ##**Sprite3D** - a three-dimensional object [block:code] { "codes": [ { "code": "Sprite3D *sprite = Sprite3D::create( \"3D object filepath\" );\n\nsprite->setTexture( \"3D objects texture filepath\" );\n// set the objects position in 3D space\nsprite->setPosition3D( Vec3( origin.x + visibleSize.width / 2, origin.y + visibleSize.height / 2, 0 ) );\n\n// set the objects rotation in 3D space\nsprite->setRotation3D( Vec3( 30, 200, -90 ) );\n\nthis->addChild( sprite );", "language": "cplusplus", "name": "Cocos2d-x C++" } ] } [/block] Note: *If the object appears small then change the scale like you would with any other node or modify the z position when using **setPosition3D*** ##**Sprite3D Animation** - a three-dimensional objects animation can be run [block:code] { "codes": [ { "code": "Sprite3D *sprite = Sprite3D::create( \"3D object filepath\" );\n/******\nset the 3D sprite's properties such as texture and position\n******/\nthis->addChild( sprite );\n\n// load the animation from the 3D object\nAnimation3D *animation = Animation3D::create( \"3D object filepath\" );\n// check if the animation exists\nif ( animation )\n{\n // create the animation for the 3D object (Animation3D *, animationStartTime, animationEndTime)\n Animate3D *animate = Animate3D::create( animation, 0, 5 );\n // speed at which the animation is run (default is 1)\n animate->setSpeed( 2 );\n // run the animation, doesn't have to be in a RepeatForever action\n sprite->runAction( RepeatForever::create( animate ) );\n}", "language": "cplusplus", "name": "Cocos2d-x C++" } ] } [/block] Note: *The start and end time for Animate3D doesn't affect its speed but what point in the animation it starts and ends. If the animation is a total of 3 seconds and the start time is 0 and the end time is 5 then the entire animation will be played. If the animation is a total of 3 seconds and the start time is 1.5 and the end time is 3 then the last half of the animation will play.* Note: *The start and end time for Animate3D are optional.* Note: ***Animate3D *animate = Animate3D::createWithFrames( animation, 0, 20 );** is an alternative to allow you to create an animation be specifying the start and end frames* ##**Camera** - the camera is the players point of view By default Cocos creates a camera as that is what is used to see the game world. But if you want to create a custom camera which faces a certain way for example it is easy to do so. There are 2 different types of cameras, perspective and orthographic: * Perspective camera takes into consideration distance hence objects further away form the camera look smaller * Orthographic camera doesn't take into consideration distance hence objects further away look the same size if they were nearer the camera [block:image] { "images": [ { "image": [ "https://files.readme.io/t2z2Um7DQkaFx2G97zM8_IC15161.jpg", "IC15161.jpg", "477", "201", "#820877", "" ] } ] } [/block] [block:code] { "codes": [ { "code": "// persective camera creation\nCamera *camera = Camera::createPerspective( fieldOfView, screenRatio, nearClippingPlane, farClippingPlane );\n// or\n// orthographic camera creation\nCamera *camera = Camera::createOrthographic( screenWidth, screenHeight, nearClippingPlane, farClippingPlane );\n\n// set parameters for camera\ncamera->setPosition3D( cameraPosition );\ncamera->lookAt( pointToLookAt, whichWayIsUp );\n\nthis->addChild( camera );", "language": "cplusplus", "name": "Camera Code Format" }, { "code": "// perspective camera creation\nCamera *camera = Camera::createPerspective( 60, ( GLfloat ) visibleSize.width / visibleSize.height, 1, 1000 );\n// or\n// orthographic camera creation\nCamera *camera = Camera::createOrthographic( visibleSize.width, visibleSize.height, nearClippingPlane, farClippingPlane );\n\n// set parameters for camera\ncamera->setPosition3D( Vec3( 0, 0, 300 ) );\ncamera->lookAt( Vec3( 0, 0, 0 ), Vec3( 0, 1, 0 ) );\n\nthis->addChild( camera ); //add camera to the scene", "language": "cplusplus", "name": "Cocos2d-x C++" } ] } [/block] Note: *The camera isn't a physical entity/object aka it can't be seen but is still very important in 3D game development.* ##**Lighting** - lighting is used to change the atmosphere and tone of the scene There are 4 different lighting techniques: * Ambient lighting - overall illumination that doesn't originate from a particular point * Directional lighting - have colour and direction but no origin/position * Point lighting - have colour and position but they have no direction as they emit light in every direction * Spot lighting - have colour, direction, position/origin and emit in a cone shape [block:image] { "images": [ { "image": [ "https://files.readme.io/UC8p1vGYQLSRKjYtMDO4_lights.png", "lights.png", "369", "109", "#b8a830", "" ] } ] } [/block] [block:code] { "codes": [ { "code": "AmbientLight *ambientLight = AmbientLight::create( lightColour );\nthis->addChild( ambientLight );\n\nDirectionLight *directionLight = DirectionLight::create( lightDirection, lightColour );\nthis->addChild( directionLight );\n\nPointLight *pointLight = PointLight::create( lightPosition, lightColour, lightRange );\nthis->addChild( pointLight );\n\nSpotLight *spotLight = SpotLight::create( lightDirection, lightPosition, lightColour, lightConeInnerAngle, lightConeOuterAngle, lightRange );\nthis->addChild( spotLight );", "language": "cplusplus", "name": "Lighting Code Format" }, { "code": "AmbientLight *ambientLight = AmbientLight::create( Color3B::YELLOW );\nthis->addChild( ambientLight );\n\nDirectionLight *directionLight = DirectionLight::create( Vec3( -1.0f, -1.0f, 0.0f ), Color3B::RED );\nthis->addChild( directionLight );\n\nPointLight *pointLight = PointLight::create( Vec3( 0.0f, 0.0f, 0.0f ), Color3B::RED, 10000.0f );\nthis->addChild( pointLight );\n\nSpotLight *spotLight = SpotLight::create( Vec3( -1.0f, -1.0f, 0.0f ), Vec3( 0.0f, 0.0f, 0.0f ), Color3B::RED, 0.0, 0.5, 10000.0f );\nthis->addChild( spotLight );", "language": "cplusplus", "name": "Cocos2d-x C++" } ] } [/block] ##**Billboarding** - technique used to make an object always face the camera [block:image] { "images": [ { "image": [ "https://files.readme.io/pXA0mz3wQ06uoWyj9KPQ_clouds.jpg", "clouds.jpg", "500", "689", "#174888", "" ] } ] } [/block] [block:code] { "codes": [ { "code": "BillBoard *billboard = BillBoard::create( imageFilepath, billboardingMode );\n\nbillboard->setPosition3D( position );\nbillboard->setBlendFunc( blendingFunction );\n\nthis->addChild( billboard );", "language": "cplusplus", "name": "Billboarding Code Format" }, { "code": "// BillBoard::Mode::VIEW_PLANE_ORIENTED or BillBoard::Mode::VIEW_POINT_ORIENTED\nBillBoard *billboard = BillBoard::create( \"Image.png\", BillBoard::Mode::VIEW_PLANE_ORIENTED );\n\nbillboard->setPosition3D( Vec3 ( 400.0f, 200.0f, 300.0f ) );\n// BlendFunc::ALPHA_NON_PREMULTIPLIED or BlendFunc::ALPHA_PREMULTIPLIED\nbillboard->setBlendFunc( BlendFunc::ALPHA_NON_PREMULTIPLIED );\n\nthis->addChild( billboard );", "language": "cplusplus", "name": "Cocos2d-x C++" } ] } [/block]