SceneKit Tutorial Part 1 - Create a SceneKit Project

In Xcode 6 Beta releases, Apple make us develop 3D games more smoothly on iOS8 by using SceneKit. SceneKit is much easier to make 3D effects like lights, shadows and textures. And it also has build-in actions and physical behaviors. This tutorial is a practical guide that show you how to make your game step by step using Xcode 6.

There is a quick start that you can use in Xcode 6.  After you've opened Xcode 6, click File from menu and go to New and then select Project to create a new project, you will see the following dialog box:

The Wizard to Create a New Project in Xcode 6

Select Game from the board and click Next. You will see the parameters for the project:

The Properties of the Project

Pay attention that you can choose SceneKit from Game Technology drop down list and Swift in Language list. After input your Project Name, Organization Name and Organization Identifier, by clicking Next and then Create button, you will create a new project like this:

Workspace of a SceneKit Project

Above are the template code written with Swift. In this tutorial, I will use Swift for demo code. And you can find all the code of this tutorial at here.

Now the new game is ready to run without any changes to the template code! Although it is just a template, you can study and start your game from beginning. The result of the SceneKit template game looks like this:

The Snapshot When SceneKit Template Project is Running

In the running game, you will see the 3D plane is rotating and you can adjust the angle of camera. You may remember the 2D plane in Sprite Kit template project, it is upgraded!

Most of time you may want to start using SceneKit from single view project, you can create one and add SceneKit.framework from Linked Frameworks and Libraries section of project panel to use SceneKit:

Select SceneKit Framework for Single View Project

In this tutorial, I've create a single view application and I will explain SceneKit code line by line. 

The Apple's SceneKit Framework Reference gives you a good introduction to SceneKit 's key concepts like coordinate system and main classes. It will help you going through the code here.

There are some other knowledges you need to know that may not mentioned in Apple's guide. Like SpriteKit, SceneKit also has the concept like scene(SCNScene) and node(SCNNode), and they are in a hierarchy relationship. Where SCNScene has a property called root node, and every other node in the scene is one of the children or descendants of the root node(Apple calls it the root of scene graph). The "other nodes" are connected with the following types of objects: geometry, light, camera and material.

The Hierarchy of a Scene

By observing above diagram, every node and the object to be present are connected. You may imagine the object to be present is a logical concept that just contains data to describe the object. For example, the light has its power and color, the geometry has its shape. But, these objects alone cannot be presented on the scene, just like a light itself cannot shine, it still need electricity to shine and some physical objects to be illumined. So SceneKit use node(SCNNode) tied all things(Geometry, Light, Scene etc) together.

In a word, SCNNode maintain its underlying object's relationship with the scene. SCNNode tell application where to put the light and how to rotate the geometry in the scene.

All right, let's show something in our application. Suppose you have created a single view application and added the SceneKit to your project. Open the Swift source file for view controller(usually named ViewController.swift) and put the following code in viewDidLoad function:

In line 4, the code created an object of SCNView which is derived from UIView. And its size is the same with current frame. Line 5 created an object to SCNScene and put the scene into the SCNView in line 6. To show the scene, we need add the SCNView as the subview of current view.

Right now, we have nothing to show in the scene, we can run the application but you device's screen will just show white blank. To put something in it, we need to create a geometry and put it into the scene:


Well, we create a box here. To create a cubic box or a chamfered box, we use SCNBox which is derived from SCNGeometry, SceneKit also requires the box associated with a SCNNode, so we connect myBox with myBoxNode and put it to the center of the coordinate system, it will be in the center of the screen. To make the cubic box looks more like a 3D box, the code rotated the node in line 4.

It is easy to understand we use SCNVector3 to keep 3 parameters of a coordinate position. SCNVector3 is used frequently in SceneKit to specify a position in 3D space. But you may wonder why we use 4-parameter SCNVector4 here to rotate the box if you are new to 3D framework. You can understand it by breaking SCNVector4 into a point in 3D space and an angle of rotation. The line formed by the point and the center of the coordinate system is the axis for the rotation and the 4th value is the angle to rotate based on the axis.

Right now, we still cannot see anything by running the application, although we have an object in the scene. That's because we haven't put a light in the scene(we can see nothing from complete dark, right?). To put a light into the scene, create a light and a node ties the light and the scene with the code:

Here we put the light on the left-top in front of the box. So the result will looks like the left picture below:

Custom Lighting

Default Lighting

Or you can use default lightning instead of creating a light and a node for light, since SCNView has a property named autoenablesDefaultLighting, we can use the following line to use the default light(the effect is on above right picture):

myView.autoenablesDefaultLighting = true

If you use default light and custom light at the same time, the effect of default lighting will be discard. The default value of autoenablesDefaultLighting is false.

Another property of SCNView that is often used is showsStatistics, it will show statistics like fps in the bottom bar of your device(You can see the bottom bar in the application created by SceneKit template project) with this line of code:

myView.showsStatistics = true

OK, I am going to stop here today, and I will continue to write the tutorial within the series. Before I stop, I want to mention that you can use the playground introduced in Xcode 6 to play with SceneKit code. It is a very cool feature of Xcode so you can use it to see the result every line you put in playground in realtime. You can refer this link for more information to try SceneKit on playground.