Intro

This article shows how to write basic shaders in the SpriteKit. It’s split into two parts: first we play, then we learn.

It also contains information how to use SKAttribute and SKAttributeValue classes that were added in iOS SDK 10.0.

If you haven’t already read it, here’s part 1 of this article series.

Prepare the project

Let’s get quick and dirty.

• Open XCode 8 and create a new project from template: iOS > Game.
• Open the GameScene.sks and remove the label in the center of the screen.
• Download this and put it inside Assets.xcassets

• Name it “Trees”
• Open the GameScene.m
• remove all instance variables
• remove all methods

The Fragment Shader

Now we create an empty fragment shader In XCode:

• In the Project Navigator select Supporting Files
• Choose: File > New > File…
• Select: Other > Empty
• Name it “myShader.fsh” and press Create.
• Put this inside:

// currently a boring pass-thru shader void main( void ) { vec4 color = texture2D(utexture, vtexcoord); // here will emerge something worthy glFragColor = color;}

Above fragment shader does nothing perceptible. Quick explanation:

• void main()
  this function gets called for each pixel of the sprite and outputs color for that pixel
  Gets input data from surrounding globals and must set the gl_FragColor variable
• vec2, vec3and vec4 are the types similar to C's: float array[2], float array[3] and float array[4]
• _utexture is a texture ID
  Leave it alone :-)
• v_tex_coord is a vec2 which contains our current position in texture
• texture2D(tex , p) is a function that returns color from texture tex in point p as vec4
  which contains rgba
• gl_FragColor is an output color
  We must assign it a vec4

Loading code

What’s left is the loading code.

• Open the GameScene.m
• add method -didMoveToView:

- (void)didMoveToView:(SKView *)view {    // 1. load the shader's source from myShaderFile.fsh    NSString *file = [[NSBundle mainBundle] pathForResource:@"myShader" ofType:@"fsh"];    NSString *sourceString = [NSString stringWithContentsOfFile:file encoding:NSUTF8StringEncoding error:nil];            // 2. create the shader    SKShader *shader = [SKShader shaderWithSource:sourceString];        // 3. assign the shader to a newly created sprite node    SKSpriteNode *spriteNode = [SKSpriteNode spriteNodeWithImageNamed:@"Trees"];    spriteNode.shader = shader;        // 4. finally add the sprite to the scene    [self addChild:spriteNode];}

Ensure that myShader.fsh figures in ProjectFile > Target > Build Phases > Copy Bundle Resources!

You may now run the project on the iOS device. There shall be no errors in the XCode’s console and you should see a screen similar to this below:

Let’s play a bit!

Now is the fun part. We’ll replace the shader’s main function.

Color with red with alpha preservation

void main( void ){    vec4 color = texture2D(u_texture, v_tex_coord);    float alpha = color.a;    gl_FragColor = vec4(1,0,0, 1.0) * alpha; //google "premultiplied alpha"}

Scale down by 2x

void main( void ){    vec4 color = texture2D(u_texture, v_tex_coord * 2.0);    gl_FragColor = color;}

Swap colors after 1 second

void main( void ){    vec4 color = texture2D(u_texture, v_tex_coord);    float alpha = color.a;    float phase = mod(u_time, 3);    vec3 outputColor = color.rgb;    if (phase < 1.0) {        outputColor = color.bgr;    } else if (phase < 2.0) {        outputColor = color.brg;    }    gl_FragColor = vec4(outputColor, 1.0) * alpha;}

Colorize over time

void main( void ){    vec4 color = texture2D(u_texture, v_tex_coord);    float alpha = color.a;    float r = (sin(u_time+ 3.14 * 0.00)+1.0)*0.5;    float g = (sin(u_time+ 3.14 * 0.33)+1.0)*0.5;    float b = (sin(u_time+ 3.14 * 0.66)+1.0)*0.5;    gl_FragColor = vec4(r,g,b, 1.0) * alpha;}

Waves

void main( void ){    float deltaX = sin(v_tex_coord.y*3.14*10 + u_time * 4)*0.01;    vec2 coord = v_tex_coord;    coord.x = coord.x + deltaX;    vec4 color = texture2D(u_texture, coord);    gl_FragColor = color;}

New Attributes

At WWDC 2016 Apple introduced an important update to SpriteKit — the SKAttribute and SKAttributeValue classes.

Before this SDK update, if we wanted to pass custom parameters into the shader program, we had to pass the data through a uniform value.

This had two serious drawbacks:

• every uniform change caused shader recompilation
• shader program handled every sprite in the exact same way

For example: if we wanted to dye a group of sprites red, and one of them blue, we had two ways. First we create two separate SKShader instances and change our custom myColor uniform.

Second we make one shader instance and change its uniform which causes a recompilation.

Both ways cannot be drawn on same pass. And the second one requires complex management code.

SDK 10.0 introduced the SKAttribute and SKAttributeValue classes. These two allow (finally!) passing data to the shader programs without recompilation. The usage algorithm is simple:

• The shader part:

• Create a shader program
  SKShader

• Create an array of SKAttributes

• Assign array of attributes to the shader program

• The sprite part:

• Assign the shader program to a sprite

• Assign a dictionary of SKAttributeValues

Example with attributes

In the last example, we’ll add two more sprites. Every one of them will have the same shader program and will differ only in attributes. Let’s modify the -didMoveToView: inGameScene.m:

- (void)didMoveToView:(SKView *)view {    NSString *file = [[NSBundle mainBundle] pathForResource:@"myShader" ofType:@"fsh"];    NSString *sourceString = [NSString stringWithContentsOfFile:file encoding:NSUTF8StringEncoding error:nil];    SKShader *shader = [SKShader shaderWithSource:sourceString];        // 1. Add a custom attribute to shader    SKAttribute *attrProgress = [SKAttribute attributeWithName:@"THE_MIGHTY_DARK_FACTOR" type:SKAttributeTypeFloat];    shader.attributes = @[attrProgress];    // 2. Create tree sprites    NSArray *trees = @[                       [self createTreeWithShader:shader mightyFactor:0.3f zPosition:1],                       [self createTreeWithShader:shader mightyFactor:0.6f zPosition:2],                       [self createTreeWithShader:shader mightyFactor:0.9f zPosition:3],                       ];    for (SKSpriteNode *tree in trees) {        [self addChild:tree];    }}- (SKSpriteNode*)createTreeWithShader:(SKShader*)shader mightyFactor:(CGFloat)mightyFactor zPosition:(CGFloat)zPosition {    SKSpriteNode *treeNode = [SKSpriteNode spriteNodeWithImageNamed:@"Trees"];    treeNode.shader = shader;    // 3. Fill the custom attribute on the sprite    treeNode.attributeValues = @{@"THE_MIGHTY_DARK_FACTOR": [SKAttributeValue valueWithFloat:mightyFactor]};    treeNode.zPosition = zPosition;return treeNode;}

… and the shader program:

void main( void ){    vec4 color = texture2D(u_texture, v_tex_coord * (2.5 * THE_MIGHTY_DARK_FACTOR));    float alpha = color.a;    vec3 baseColor = color.rgb * THE_MIGHTY_DARK_FACTOR;    gl_FragColor = vec4(baseColor, 1.0) * alpha;}

... and see the parameterized result!

Caveats

• The shader’s source code is typically loaded from a .fsh file to a plain NSString
  This code must compile on the target device during the runtime
  no buildtime checks!
• Older devices may use different version of OpenGL ES so beware GLSL syntax differences!
  In Raft Challenge’s case there was the need to replace __constant (valid in OpenGL ES 3.0) to const for OpenGL ES 2.0.
• It’s a good idea to keep a reference to SKShader object somewhere and reuse it as frequently as needed to avoid visible frame rate drop
  While allocation and shader compilation takes less than 1/60 sec, it may become a huge burden in render loop
• When using SpriteKit’s Texture Atlases be cautious of vtexcoord
  XCode may rotate some textures which swap X and Y axis
  Color modification is safe, geometry is not

Summary

We learned by examples how to use fragment shaders in the Sprite Kit. We added parameters to sprites so our shader program can render every instance in a different way without any performance loss.

The complete project is available for a download.

You can read part 3 of this series here.

About the author: Kamil Ziętek is an iOS Developer at www.allinmobile.co

Intro

This article is about graphical evolution of Raft Challenge from the prototype to the final product. It’s AIM-ed for the people who are thinking about making their own game with graphics like Raft, but don’t know exactly how to start.

The very beginning of Raft Challenge

Raft Challenge was born during the first hackathon organized by All In Mobile. The idea was to make a game where a player avoids obstacles. We wanted to keep things as simple as possible.

After the weekend, we had a prototype that looked like this:

Raft Challenge won the hackathon. The company announced that it’ll make the resources to improve the game.

Let’s make it 2,5D!

At the start of the project, Raft had the simplest possible graphics. A view was directly over a flat ground texture, with colored circles that indicated the player and the enemies. It was beautiful and as simple as the code underneath. Then our graphic designer came and messed up everything. He said, “Let’s make it 2,5D!”. The challenge was accepted and the animation above was the result.

After the hackathon he showed up once again. This time it was something more than one sentence.

It was an evil smile and this video:

Perspective explained

Ok, let’s drop the act :-). I’ve wanted to give him the feeling that he’s in charge. But I’m the boss here! The perspective is easy to implement in code, regardless of what 2D engine we use.

First, we have to determine where we want to put the vanishing point. The example below shows this point in the center of the canvas.

Raft Challenge has this point in the upper half of the screen, because the sky and everything overhead isn’t as important as obstacles on the river.

How are the sprites themselves made? While it may be obvious for someone with artistic background, it isn’t necessarily clear for a technical person.

There are two rules:

• Moving parts must be drawn along the helper lines as shown above
  All those lines intersect in the vanishing point

Note: The coast part isn’t reaching the vanishing point. It stops somewhere in the middle, leaving the transparent area behind.

• That empty area between the graphic and the vanishing point has an important purpose
  It’ll hold elements that are further away.

Those parts are made by applying a twice smaller scale for each step. The resulting image should be seamless if the texture is well-made.

Assembling the scene

After we’ve prepared all our assets, we need to put them all into the scene.

Let’s see how it looks in Raft Challenge.

Starting from the bottom:

1. Background layers
   Background
   Grass
   Fog bottom
   Sun
   Mountains
   Horizon Line

2. These layers are all static they don’t move

3. Background acts for both the sky and water
4. The background is a plain gradient
   It’s stretched to fill the entire device’s screen
   The aspect ratio is ignored
5. We may merge layers other than Background for increased performance unless we want to change some properties

6. We may move the sun during the gameplay
   or replace mountains for something different

7. Perspective layers
   Trees with reflections
   Coast
   Obstacles

8. For the clarity of the image above, layers with similar content were grouped
   There were:
   2 layers of Obstacles
   8 layers of Coast
   8 layers of Trees with reflections

9. These layers are scaled up by 2 when a player is moving forward

10. Order of these layers depends on
    distance
    closer ones are on top
    priority
    Obstacle > Coast > Trees

11. Character

12. If an Obstacle is in the closest possible position, it may have z-position higher than the Character itself
    In this case, the Obstacle covers the Character, which is desirable

13. GUI

14. Good graphics should depend on illusions and tricks instead of hardware

Summary

This article should give us an idea how to approach the problem of making assets to a 2,5D game and organizing them into a scene.

You can read part 2 of this series here.

About the author: Kamil Ziętek is an iOS Developer at www.allinmobile.co