3D

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.

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

Sprite3D *sprite = Sprite3D::create( "3D object filepath" );

sprite->setTexture( "3D objects texture filepath" );
// set the objects position in 3D space
sprite->setPosition3D( Vec3( origin.x + visibleSize.width / 2, origin.y + visibleSize.height / 2, 0 ) );

// set the objects rotation in 3D space
sprite->setRotation3D( Vec3( 30, 200, -90 ) );

this->addChild( sprite );

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

Sprite3D *sprite = Sprite3D::create( "3D object filepath" );
/******
set the 3D sprite's properties such as texture and position
******/
this->addChild( sprite );

// load the animation from the 3D object
Animation3D *animation = Animation3D::create( "3D object filepath" );
// check if the animation exists
if ( animation )
{
  // create the animation for the 3D object (Animation3D *, animationStartTime, animationEndTime)
  Animate3D *animate = Animate3D::create( animation, 0, 5 );
  // speed at which the animation is run (default is 1)
  animate->setSpeed( 2 );
  // run the animation, doesn't have to be in a RepeatForever action
  sprite->runAction( RepeatForever::create( animate ) );
}

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

// persective camera creation
Camera *camera = Camera::createPerspective( fieldOfView, screenRatio, nearClippingPlane, farClippingPlane );
// or
// orthographic camera creation
Camera *camera = Camera::createOrthographic( screenWidth, screenHeight, nearClippingPlane, farClippingPlane );

// set parameters for camera
camera->setPosition3D( cameraPosition );
camera->lookAt( pointToLookAt, whichWayIsUp );

this->addChild( camera );

// perspective camera creation
Camera *camera = Camera::createPerspective( 60, ( GLfloat ) visibleSize.width / visibleSize.height, 1, 1000 );
// or
// orthographic camera creation
Camera *camera = Camera::createOrthographic( visibleSize.width, visibleSize.height, nearClippingPlane, farClippingPlane );

// set parameters for camera
camera->setPosition3D( Vec3( 0, 0, 300 ) );
camera->lookAt( Vec3( 0, 0, 0 ), Vec3( 0, 1, 0 ) );

this->addChild( camera ); //add camera to the scene

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

AmbientLight *ambientLight = AmbientLight::create( lightColour );
this->addChild( ambientLight );

DirectionLight *directionLight = DirectionLight::create( lightDirection, lightColour );
this->addChild( directionLight );

PointLight *pointLight = PointLight::create( lightPosition, lightColour, lightRange );
this->addChild( pointLight );

SpotLight *spotLight = SpotLight::create( lightDirection, lightPosition, lightColour, lightConeInnerAngle, lightConeOuterAngle, lightRange );
this->addChild( spotLight );

AmbientLight *ambientLight = AmbientLight::create( Color3B::YELLOW );
this->addChild( ambientLight );

DirectionLight *directionLight = DirectionLight::create( Vec3( -1.0f, -1.0f, 0.0f ), Color3B::RED );
this->addChild( directionLight );

PointLight *pointLight = PointLight::create( Vec3( 0.0f, 0.0f, 0.0f ), Color3B::RED, 10000.0f );
this->addChild( pointLight );

SpotLight *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 );
this->addChild( spotLight );

Billboarding - technique used to make an object always face the camera

BillBoard *billboard = BillBoard::create( imageFilepath, billboardingMode );

billboard->setPosition3D( position );
billboard->setBlendFunc( blendingFunction );

this->addChild( billboard );

// BillBoard::Mode::VIEW_PLANE_ORIENTED or BillBoard::Mode::VIEW_POINT_ORIENTED
BillBoard *billboard = BillBoard::create( "Image.png", BillBoard::Mode::VIEW_PLANE_ORIENTED );

billboard->setPosition3D( Vec3 ( 400.0f, 200.0f, 300.0f ) );
// BlendFunc::ALPHA_NON_PREMULTIPLIED or BlendFunc::ALPHA_PREMULTIPLIED
billboard->setBlendFunc( BlendFunc::ALPHA_NON_PREMULTIPLIED );

this->addChild( billboard );