Textures

How to add textures to GameItems in the Kakara Engine.

A gray cube is cool and all, but it would be nice to add our own texture to it. The texture format of a mesh depends on the texture coordinates (UVs) provided. For a primitive cube (via CubeData) the format is:

An example texture for a cube.

We will be adding the above texture to our cube. You can pick your own texture to add if you want.

Adding a File to the Game

Before we can do anything with the code, we need to add the file to our game. We do this by adding it to the resources folder. We want to create the resources folder to put our resources inside of. If using Maven or Gradle there will already be a resources folder, you want to create another folder named resources inside that folder.

File Hierarchy for Maven or Gradle (packages excluded)

Using the Resource Manager

The Kakara Engine provides an easy way to obtain resources within the engine. You can access it through the GameHandler. (Add this code before setting the material of the cube mesh).

ResourceManager rm = gameHandler.getResourceManager();

From there you can use the getResource() method to get a resource.

Creating a Texture

Now that we have our ResourceManager we need to create a texture. We can do that by constructing a new texture and passing it our resource and the scene instance.

Texture cubeTexture = new Texture(rm.getResource("/Example_Cube.png"), this);

Textures are a Graphical process and can only be created on the primary game thread.

Adding a Texture to a Material

Now that we created our texture, we want to add it to the Material of our mesh. We can do that by using the setTexture() method.

cubeMaterial.setTexture(cubeTexture);

Now if you run the game you should see a fully texture cube:

A fully texture cube.

Full Code

MainScene.java

import org.kakara.engine.GameHandler;
import org.kakara.engine.engine.CubeData;
import org.kakara.engine.gameitems.GameItem;
import org.kakara.engine.gameitems.Material;
import org.kakara.engine.gameitems.Texture;
import org.kakara.engine.gameitems.mesh.Mesh;
import org.kakara.engine.resources.ResourceManager;
import org.kakara.engine.scene.AbstractGameScene;

public class MainScene extends AbstractGameScene {
    public MainScene(GameHandler gameHandler) {
        super(gameHandler);
    }

    @Override
    public void work() {

    }

    @Override
    public void loadGraphics(GameHandler gameHandler) throws Exception {
        Mesh cubeMesh = new Mesh(CubeData.vertex, CubeData.texture, 
            CubeData.normal, CubeData.indices);
        Material cubeMaterial = new Material();

        ResourceManager rm = gameHandler.getResourceManager();
        Texture cubeTexture = new Texture(rm.getResource("/Example_Cube.png"), 
            this);
        cubeMaterial.setTexture(cubeTexture);

        cubeMesh.setMaterial(cubeMaterial);

        GameItem gameItem = new GameItem(cubeMesh);
        gameItem.transform.setPosition(0, 0, -10);
        gameItem.addComponent(RotateCube.class);

        add(gameItem);
    }

    @Override
    public void update(float v) {

    }
}

Possible Errors You Can Encounter

Generic Load Exception

If you get a GenericLoadException that states Error: Cannot load specified image. than that means the file cannot be found or the game engine does not have access to it. There should be a more specific message that following the above statement. Ensure that you typed the file path correctly and have the file in the right location.

IO Exception

You can also get an IOException if the file is not found or if the engine does not have permission to read it. Once again ensure that you typed the file path correctly and the file is in the right location.