How do you add entities to a Sprite Kit scene using the Xcode Sprite Kit scene editor?

Question

According to the Sprite Kit documentation for entities and components

When you add entities (and their components) to a scene in the Xcode SpriteKit Scene Editor, Xcode automatically archive those entities alongside the SpriteKit scene content.

This implies that you can add entities using the scene editor, but I can't find any way to do that. I can add components using the node components inspector, but not entities. How is this done?

Magma

Answer 1

Your entities are not added in the SpriteKit scene - they are added in the abstract GKScene.

When you are using the SpriteKit editor, you can think of your nodes as your entities; if you add a component to a sprite, say, and then load up the GKScene, you'll have an entity with two components: the component you added to the sprite, and a GKSKNodeComponent that points to the node.

What the Sprite Kit scene editor is allowing you to do is to have a nice mapping from a GKScene (which has no particular knowledge of a SpriteKit scene or its structure) and a SpriteKit scene by automatically creating entities representing an SKScene's nodes, and giving you a way to attach components to the entities that are associated with their sister nodes in the SKScene, so that you don't have to do it programmatically.

You can, of course, add your own abstract entities and attach components to them beyond the ones that the SpriteKit scene editor supplies. But currently, you'll have to do that programmatically outside of the scene editor, because the scene editor has no concept of an entity that is not associated with a node. (However, I suspect you'll find that you can just use an empty SKNode to act as a container for those types of components, and it will be a lot easier to manage with very little overhead. In other words, I don't think you'd get much value from manually managing those entities and components in code compared to being able to work with them alongside everything else in the SpriteKit scene editor.)

Lingo

Hi cc. Are you saying that I can do some kind of external map, and then translate that into Scene Editor of SpriteKit? How can I do this? I want to make a mapping of the paths for the level externaly (e.g. a .txt file), and then have that translated into .sks file as sprites. – Imbricate

I don't know if there's a way to translate that into the Scene Editor - I don't believe there's a way to script the Scene Editor like that. But you could certainly do what you describe at runtime with a component that reads the .txt file and creates the sprites in the SKScene it is associated with. Alternatively, you could put the sprites in the .sks file, and then your component reads the .txt file and grabs references to the nodes at runtime using the usual methods. – Lingo

Hi cc. Could you show an example of what you described for automated creation of entity to the Scene's node? What is the prerequisite before the automation starts? I can just create the my own entity with a scene node programmatically which has no automation at all inside. Could you explain this more clearly? – Caves

@SungwookKim - Not sure I understand what you're asking, but if you're looking to programmatically create a SKScene/GKScene node, as opposed to doing it in the SpriteKit scene editor, you'd basically just create a GK entity for the game object and add it to the GKScene. Then, to connect that game object to the SpriteKit scene, you would create the SKNode representing that object in the SKScene, and then create a GKSKNodeComponent tying the two together and put that in the corresponding entity. (If you need more detail on this, maybe create a new SO thread.) – Lingo

Thanks! CC. If I add any component to the SKNode added on scene editor, I think the node will start to act as entity instantly. Is it right? – Caves

You can certainly think of it like that. Really what's happening is that it creates an entity object, adds your component to it, and also adds a GKSKNodeComponent to it that points to the SKNode. In other words, an SKNode is not a GKEntity – your node is pointed to by a component in an entity. But there is a tight relationship between the SKScene nodes and the GKScene entities, so when using the editor, you can think of your nodes as entities. Just be aware of the above when writing component code; you'll need to understand that distinction to get references to your nodes in the SKScene. – Lingo

Answer 2

An entity is automatically created and added to the array of entities in the SKScene when a component is added to a SKNode in the scene editor:

1. Create a subclass of GKComponent.
2. Open the Scene Editor (click on your GameScene.sks).
3. Select one of the items in the scene (or add one from the library).
4. Open the Components Inspector (opt-cmd-7) and click the plus (+) to select your GKComponent subclass.

You can see an entity is created by adding the following snippet to the scene's update(_:) method. The snippet accesses each entity, searches for a component for GKSKNodeComponent (which was added by the scene editor when you added a component to a SKNode), and then accesses its node (your item(s) in the scene with components added to them):

for entity in self.entities {
    if let node = entity.component(ofType: GKSKNodeComponent.self)?.node {
        print("node: \(node)")
    }
}

Since iOS 13 there has been a bug where there would be problems loading the rootNode from the GKScene so GameplayKit projects and the above technique would not work... UNLESS you add the following to your custom GKComponent subclass:

override class var supportsSecureCoding: Bool {
    return true
}

Yawn