Bare minimum example of how to use input to control entities for games

[BrentFarris]

This is going to be a guide, from scratch, on how to get inputs/controls working in a game. We'll start from the very beginning of creating a project, up through the code for controlling a 2D sprite. This input guide will translate to 3D with minimal effort.

Create a project

Start by setting a name for your project and selecting the folder you want to create it in.

Importing content

Follow the on-screen instructions to import an image file. Start by clicking on the "Content" tab.

Next, click on the "Import content..." button.

After finding the image you want to import from your computer and importing it. You should see it in the content browser.

Putting the sprite on the stage

Go back to the "Stage" tab and then select the "2D" button at the top of the viewport to switch to the 2D view.

Next, drag/drop your image into the view port from the content list at the bottom.

Next, select "Create" from the menu bar, then select "Entity Data"

Next, fill in the name and select the path (in the project) you'd like to save the code.

The code

This should automatically launch your code editor, if not, navigate to the file and open it up in your code editor. You should see something like the following:

package input_test

import "kaijuengine.com/engine"

func init() {
	engine.RegisterEntityData(TestMove{})
}

type TestMove struct {
    // Setup your POD
}

func (d TestMove) Init(entity *engine.Entity, host *engine.Host) {
    // host.Updater.AddUpdate = create update, host.Game() = *game_host.GameHost
}

Please be sure to review the full source code comments (at the bottom of this section) for a complete picture.

Let's start by adding a Speed field to the TestMove struct. Note that this MUST be a POD (plain ol' data) int, bool, string, float32, etc.. Note that you can also use structures with only those POD types. Don't put pointers or other non-compound simple types in here.

type TestMove struct {
	Speed float32
}

After that, we'll add an update to our host Updater. The Updater runs any update functions registered to it in parallel (across threads). Every time you add an update, it will return the handle to that update. This handle will allow you to cancel the update in the future, should you wish to. We do just that when the entity is destroyed by registering to the OnDestroy event of the entity.

Be careful in the future when creating functions that capture state "willy-nilly" in the future, you may want to be passing weak pointers instead.

func (d TestMove) Init(entity *engine.Entity, host *engine.Host) {
	updateId := host.Updater.AddUpdate(func(deltaTime float64) {
		update(host, entity, deltaTime, d.Speed)
	})
	entity.OnDestroy.Add(func() { host.Updater.RemoveUpdate(&updateId) })
}

Next, we'll setup our update function that is called every frame. Note that you can get the mouse, controller, touch, and stylus the same way we get the keyboard here.

func update(host *engine.Host, entity *engine.Entity, dTime float64, speed float32) {
	kb := &host.Window.Keyboard
	v := matrix.Vec3Zero()
	if kb.KeyHeld(hid.KeyboardKeyW) {
		v.AddY(speed) // Up
	}
	if kb.KeyHeld(hid.KeyboardKeyS) {
		v.AddY(-speed) // Down
	}
	if kb.KeyHeld(hid.KeyboardKeyA) {
		v.AddX(-speed) // Left
	}
	if kb.KeyHeld(hid.KeyboardKeyD) {
		v.AddX(speed) // Right
	}
	if v.IsZero() {
		return
	}
	delta := v.Normal().Scale(float32(dTime))
	entity.Transform.AddPosition(delta)
}

Below is the complete code example:

package input_test

import (
	"kaijuengine.com/engine"
	"kaijuengine.com/matrix"
	"kaijuengine.com/platform/hid"
)

func init() {
	engine.RegisterEntityData(TestMove{})
}

type TestMove struct {
	Speed float32
}

func (d TestMove) Init(entity *engine.Entity, host *engine.Host) {
	// The following is a very simple (and safe) implementation of
	// this test. However, in production, you'd like to collect
	// updates into managers and thus manage the state/flow of your
	// game in a different way. Having an update for each entity
	// isn't very efficient.
	//
	// You have access to your game mediator through the host.Game()
	// function call. You can do this to get your main game code
	// then access the rest of your game system from there. Much like
	// Kaiju accesses it's entire system through the host mediator.

	// host.Updater runs an update function, every frame, threaded
	updateId := host.Updater.AddUpdate(func(deltaTime float64) {
		// Just capturing state here for simplicity
		update(host, entity, deltaTime, d.Speed)
	})
	// Remove the update when the entity is destroyed
	entity.OnDestroy.Add(func() { host.Updater.RemoveUpdate(&updateId) })
}

func update(host *engine.Host, entity *engine.Entity, dTime float64, speed float32) {
	// Get the poniter to the keyboard to check inputs
	kb := &host.Window.Keyboard
	// Create a null vector for velocity calculation
	v := matrix.Vec3Zero()
	// Check if key is pressed
	if kb.KeyHeld(hid.KeyboardKeyW) {
		v.AddY(speed) // Up
	}
	if kb.KeyHeld(hid.KeyboardKeyS) {
		v.AddY(-speed) // Down
	}
	if kb.KeyHeld(hid.KeyboardKeyA) {
		v.AddX(-speed) // Left
	}
	if kb.KeyHeld(hid.KeyboardKeyD) {
		v.AddX(speed) // Right
	}
	if v.IsZero() {
		return
	}
	// Normalize the velocity and scale by time
	delta := v.Normal().Scale(float32(dTime))
	// Transpose the entity
	entity.Transform.AddPosition(delta)
}

Setting up the main stage

Return to the editor and click "File" then click "Save stage"

You can call your stage whatever you'd like, I tend to call my entry point stage main.

Next, select your entity on the stage and then go to the properties panel on the right. Scroll down to the search box at the bottom to search for the entity data we just created. Click on the entity data to attach it.

Set the speed to something like 10, then create a camera by clicking on "Create" in the menu bar, and selecting "Camera".

Update your camera to ensure that it's at the right position, rotation, scale, is orthographic, and is the primary camera.

1. Double check your camera is correctly positioned
2. Currently there is a bug where the camera needs to be rotated 180 degrees to face "forward", ensure that's set, we'll fix that to auto-rotate 180 degrees in the future
3. Set the width/height, in the image I'm using a 16:9 ratio
4. Set the camera to "Orthographic"
5. Ensure the camera is set to be the main camera

Testing

Now click "File" and then "Build and run game" to compile and start the game.

At this point, a window should open up, you should see your image, and you should be able to move it around with the W/A/S/D keys.