Controls (Virtual Gamepad)

Provides ready-to-use joystick and action buttons for touch devices. Runs entirely client-side with zero external dependencies.

Two usage modes are available:

1. JS API — Programmatic control via gameTegra.controls.*
2. Custom Elements — <gametegra-joystick> and <gametegra-buttons> HTML tags

controls.show

Shows controls on screen. By default creates an analog joystick (left) + A/B buttons (right).

JavaScript

// Default: analog joystick + A/B buttons
gameTegra.controls.show()

// Custom configuration
gameTegra.controls.show({
  joystick: { type: 'dpad' },
  buttons: [
    { code: 'fire',  label: 'Fire',  icon: 'crosshair' },
    { code: 'jump',  label: 'Jump',  icon: 'arrow_up' },
  ],
  opacity: 0.8,
  theme: 'dark',
})

// Render into your own container
gameTegra.controls.show({
  target: 'game-controls',
})

Parameters (ControlsConfig):

Field	Type	Required	Default	Description
target	string	No	null	HTML element ID — renders inside that element if provided, otherwise fixed overlay
joystick	boolean | object	No	true	false=disabled, true=analog, or object like { type: 'dpad' }
buttons	array | false	No	[A, B]	Button list or false (no buttons)
opacity	number	No	0.7	Control opacity (0-1)
theme	string	No	'dark'	'dark' or 'light'

Joystick Config:

Field	Type	Required	Default	Description
type	string	No	'analog'	'analog' or 'dpad'
size	number	No	120	Diameter (px)
deadZone	number	No	0.15	0-1 range — center sensitivity in analog mode
diagonals	boolean	No	true	false → only 4 directions (up/down/left/right)

Button Config:

Field	Type	Required	Description
code	string	Yes	Event code (e.g. 'fire', 'jump')
label	string	No	Text displayed on the button
icon	string	No	Built-in icon name, raw SVG string, or null

Built-in Icons: circle, cross, crosshair, arrow_up, lightning, stop, shield, sword

---

controls.on

Listens for a specific control code.

JavaScript

// Listen for button events
const unsub = gameTegra.controls.on('fire', (e) => {
  console.log(e.type) // 'press' or 'release'
})

// Listen for joystick direction
gameTegra.controls.on('up', (e) => {
  console.log('Moving up')
})

// Joystick released
gameTegra.controls.on('idle', (e) => {
  console.log('Joystick idle')
})

// Stop listening
unsub()

Parameters:

Field	Type	Required	Description
code	string	Yes	Event code to listen for
handler	function	Yes	Callback function

Return Type: () => void — function to stop listening

Event Object:

Field	Type	Description
code	string	Event code (e.g. 'fire', 'up', 'idle')
type	string	'press', 'release', or 'move'
timestamp	number	Timestamp in milliseconds

Joystick Direction Codes: up, down, left, right, up_left, up_right, down_left, down_right, idle

---

controls.onAny

Listens for all control events with a single handler.

JavaScript

const unsub = gameTegra.controls.onAny((e) => {
  console.log(`${e.code}: ${e.type}`)
})

---

controls.hide

Removes controls from screen but preserves event listeners. Can be shown again with show().

JavaScript

gameTegra.controls.hide()

---

controls.destroy

Completely destroys controls — DOM, CSS, and all listeners are cleaned up.

JavaScript

gameTegra.controls.destroy()

---

Custom Elements

When the SDK loads, <gametegra-joystick> and <gametegra-buttons> custom elements are automatically registered. They can be used directly in HTML.

<!-- Analog joystick (default) -->
<gametegra-joystick></gametegra-joystick>

<!-- D-Pad -->
<gametegra-joystick type="dpad"></gametegra-joystick>

<!-- Custom size -->
<gametegra-joystick type="analog" size="150"></gametegra-joystick>

<!-- Custom buttons -->
<gametegra-buttons buttons='[{"code":"fire","label":"Fire","icon":"crosshair"},{"code":"jump","label":"Jump","icon":"arrow_up"}]'>
</gametegra-buttons>

Custom elements use the same event system — listen with gameTegra.controls.on().

Multi-Touch

Joystick and buttons can be used simultaneously. Each tracks independent touch identifiers.

Target Mode

When a target parameter is provided, controls render inside the specified HTML element instead of a fixed overlay. This lets you position them within a specific area of your game.

---

Full Example

// Show controls
gameTegra.controls.show({
  joystick: { type: 'analog', deadZone: 0.2 },
  buttons: [
    { code: 'fire',  label: 'Fire',  icon: 'crosshair' },
    { code: 'jump',  label: 'Jump',  icon: 'arrow_up' },
    { code: 'shield', label: 'Shield', icon: 'shield' },
  ],
  theme: 'dark',
  opacity: 0.8,
})

// Listen for directions
gameTegra.controls.on('up', () => player.moveUp())
gameTegra.controls.on('down', () => player.moveDown())
gameTegra.controls.on('left', () => player.moveLeft())
gameTegra.controls.on('right', () => player.moveRight())
gameTegra.controls.on('idle', () => player.stop())

// Listen for buttons
gameTegra.controls.on('fire', (e) => {
  if (e.type === 'press') player.startFiring()
  if (e.type === 'release') player.stopFiring()
})

gameTegra.controls.on('jump', (e) => {
  if (e.type === 'press') player.jump()
})

// Log all events
gameTegra.controls.onAny((e) => {
  console.log(`[${e.code}] ${e.type}`)
})

// Clean up when game ends
gameTegra.controls.destroy()

Simple D-Pad Example

gameTegra.controls.show({
  joystick: { type: 'dpad' },
  buttons: [{ code: 'action', label: 'A', icon: 'circle' }],
})

gameTegra.controls.on('up',    () => move('up'))
gameTegra.controls.on('down',  () => move('down'))
gameTegra.controls.on('left',  () => move('left'))
gameTegra.controls.on('right', () => move('right'))
gameTegra.controls.on('action', (e) => {
  if (e.type === 'press') doAction()
})