ctrl

Documentation

Overview

Package ctrl gives the users the ability to use a valve style controller API to deal with all major controller {kb+m, steam, ps3, ps4, xbox360, xboxone}. To use the API start by importing ctrl and any driver package you want, verify if your platform supports it.

import (
	"github.com/luxengine/ctrl"
	_ "github.com/luxengine/ctrl/glfw"
	_ "github.com/luxengine/ctrl/steam"
)

Folling Valve's model, the first you have to do is declare a file that explains what are the actions you expect to be exposed. Super Mario Bros (NES) would define 4-7 actions (depending on how you count), "move", "jump", "run" and "pause". Note that this initial file does NOT bind any key to the actions, it only defines what are the expected actions.

There are 2 types of possible actions, digital actions and analog actions. digital actiosn represent everything is either on or off (like buttons), while digital actions represent everything that have a range of values, including mouse, joysticks and touch points.

Since the same button can be used both inside eg. in-menus and in-game, we wrap actions in action sets. Only one action set can be active at a time and actions that aren't in the active set are disabled until their owner set is activated.

Once you have your actions defined you must make a default binding in another file (or any io.Reader), these bind actions to specific devices (buttons/mouse/joystick). This allows players to change their configuration much more easilly.

The API usage should look like this:

//import all the stuff
//somehow read the necessary action file and default binding
p1 := GetConnectedControllers()[0] // or give one to each player
ingame := p1.GetActionSet("callofdutyingame")
ingame.Activate() // this makes the in-game action set the acive one
fire := ingame.GetDigitalAction("fire")
...
if fire.Data().Pressed() {
	// fire some bullets
}

Having this setup, as valve explained, allow for configuration to be swapped much more easily while the app is running and, according to a lot of people who use steam controllers, is really fun to use. Also glfw/ps/xbox do not define any sort of API to use the device while steam does, so why force things.

Index

• func AddDriver(d Driver)
• func Update()
• type ActionSet
• type ActionSetFormat
  • func LoadCtrlFormat(r io.Reader) (ActionSetFormat, error)
• type AnalogAction
• type AnalogActionData
• type Controller
  • func GetConnectedControllers() []Controller
• type ControllerSourceMode
• type DigitalAction
• type DigitalActionData
• type Driver
• type IActionSet

Functions

func AddDriver

func AddDriver(d Driver)

AddDriver adds the given driver {kb+m, steam, ps(3|4), xbox(360|one)} to be used. Only driver packages should be calling this function.

func Update

func Update()

Update gives a change for every driver to poll their inputs. This must be called once per frame.

Types

type ActionSet

type ActionSet struct {
	Name         string `json:"name"`
	Stickpadgyro []struct {
		Name      string `json:"name"`
		Inputmode string `json:"inputmode"`
	} `json:"stickpadgyro"`
	Analogtriggers []struct {
		Name string `json:"name"`
	} `json:"analogtriggers"`
	Buttons []string `json:"buttons"`
}

type ActionSetFormat

type ActionSetFormat struct {
	Actionsets []ActionSet `json:"actionsets"`
}

ActionSetFormat holds the action sets + actions available to the players.

func LoadCtrlFormat

func LoadCtrlFormat(r io.Reader) (ActionSetFormat, error)

LoadCtrlFormat will load the formatted controller file and passes the actionset/action structure to all controllers. It's important to understand that this data only explain what the different actions sets and actions are and not their bindings.

type AnalogAction

type AnalogAction interface {
	// Data reads the state of the in-game action.
	Data() AnalogActionData

	// Name returns the localized name of the action
	Name() string

	// ActionSet returns the parent action set.
	ActionSet() ActionSet

	// GetOrigin returns the origin of the action input, this is used to find
	// the appropriate glyph (image) to use with the associated action. Eg.
	// display the A xbox image when trying to talk to an NPC.
	GetOrigin() struct{}
}

AnalogAction is a action that the player can take, they represent all actions that have non boolean status (mouse, joysticks, etc). Actions are tied to a specific instance of a ActionSet.

type AnalogActionData

type AnalogActionData struct {
	// Type of data coming from this action, this will match what got specified
	// in the action set
	Mode ControllerSourceMode

	// Whether or not this action is currently available to be bound in the
	// active action set
	Active bool

	// The current state of this action; will be delta updates for mouse or
	// joysticks actions and for trigger like mechanism only the X value will be
	// filled.
	X, Y float32
}

AnalogActionData is the data returned from AnalogAction queries.

type Controller

type Controller interface {
	// Name returns the name of the controller, "Keyboard+Mouse", "ps3 1", etc
	// different controllers from the same driver should return different names.
	// Names should adjust when controllers disconnect/reconnect/are added.
	Name() string

	// GetActionSet returns the action set with the given name. Should be called
	// once at game startup but needs it needs to be possible to call this
	// repetitively without any problem. Return nil if the set is not found.
	GetActionSet(string) IActionSet

	// LoadControllerConfiguration maps the button to the action sets.
	LoadControllerConfiguration(struct{}) error
}

Controller is the generic interface for any of the supported controllers.

func GetConnectedControllers

func GetConnectedControllers() []Controller

GetConnectedControllers returns the slice of currently connected controller.

type ControllerSourceMode

type ControllerSourceMode int16

ControllerSourceMode is an enum for the types of mode analog signals can have.

const (
	None ControllerSourceMode = iota
	Dpad
	Buttons
	FourButtons
	AbsoluteMouse
	RelativeMouse
	JoystickMove
	JoystickCamera
	ScrollWheel
	Trigger
	TouchMenu
)

The different controller source mode

type DigitalAction

type DigitalAction interface {
	// Data reads the state of the in-game action.
	Data() DigitalActionData

	// Name returns the localized name of the action
	Name() string

	// ActionSet returns the parent action set.
	ActionSet() ActionSet

	// GetOrigin returns the origin of the action input, this is used to find
	// the appropriate glyph (image) to use with the associated action. Eg.
	// display the A xbox image when trying to talk to an NPC.
	GetOrigin() struct{}
}

DigitalAction is a action that the player can take, they represent buttons that are either pressed or not. Actions are tied to a specific instance of a ActionSet.

type DigitalActionData

type DigitalActionData struct {
	// Whether or not this action is currently available to be bound in the
	// active action set.
	Active bool

	// The current state of this action; will be true if currently pressed
	State bool
}

DigitalActionData is the data returned from DigitalAction queries.

type Driver

type Driver interface {
	// GetConnectedControllers returns the list of controllers this Driver can
	// support
	GetConnectedControllers() []Controller

	// Update gives a chance to poll the controllers.
	Update()

	// LoadFormat explain the different actions sets that are available to the
	// players
	LoadFormat(ActionSetFormat)
}

Driver is the generic driver interface for any of the supported controllers.

type IActionSet

type IActionSet interface {
	// GetDigitalAction returns the DigitalAction associated with the given
	// string.
	GetDigitalAction(string) DigitalAction

	// GetAnalogAction returns the DigitalAction associated with the given
	// string.
	GetAnalogAction(string) AnalogAction

	// Activate sets this ActionSet as the active action set with the associated
	// controller. It needs to be possible to call this repetitively without
	// problems.
	Activate()

	// Name returns the localized name of the actionset.
	Name() string
}

IActionSet is a handle to a list of actions that the user can activate, such as jumping, firing, interracting with the environnement, opening menus. ActionSet instances are tied to a specific controller.