Controls (Virtual Gamepad)

Dokunmatik cihazlarda kullanilmak uzere hazir joystick ve aksiyon butonlari sunar. Tamamen client-side calisir, dis bagimliligi yoktur.

Iki kullanim modu vardir:

1. JS API — gameTegra.controls.* ile programatik kontrol
2. Custom Elements — <gametegra-joystick> ve <gametegra-buttons> HTML tag'leri

controls.show

Kontrolleri ekranda gosterir. Varsayilan olarak analog joystick (sol) + A/B butonlari (sag) olusturur.

JavaScript

// Varsayilan: analog joystick + A/B butonlari
gameTegra.controls.show()

// Ozel yapilandirma ile
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',
})

// Kendi container'ina render et
gameTegra.controls.show({
  target: 'game-controls',
})

Parametreler (ControlsConfig):

Alan	Tip	Zorunlu	Varsayilan	Aciklama
target	string	Hayir	null	HTML element ID — verilirse o elementin icine render eder, verilmezse fixed overlay
joystick	boolean | object	Hayir	true	false=kapali, true=analog, { type: 'dpad' } gibi obje
buttons	array | false	Hayir	[A, B]	Buton listesi veya false (butonsuz)
opacity	number	Hayir	0.7	Kontrol opakligi (0-1)
theme	string	Hayir	'dark'	'dark' veya 'light'

Joystick Config:

Alan	Tip	Zorunlu	Varsayilan	Aciklama
type	string	Hayir	'analog'	'analog' veya 'dpad'
size	number	Hayir	120	Cap (px)
deadZone	number	Hayir	0.15	0-1 arasi — analog modda merkez hassasiyeti
diagonals	boolean	Hayir	true	false → sadece 4 yon (yukari/asagi/sol/sag)

Button Config:

Alan	Tip	Zorunlu	Aciklama
code	string	Evet	Event kodu (ornegin 'fire', 'jump')
label	string	Hayir	Buton uzerinde gosterilecek metin
icon	string	Hayir	Built-in ikon adi, raw SVG string veya null

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

---

controls.on

Belirli bir kontrol kodunu dinler.

JavaScript

// Buton event'i dinle
const unsub = gameTegra.controls.on('fire', (e) => {
  console.log(e.type) // 'press' veya 'release'
})

// Joystick yon event'i dinle
gameTegra.controls.on('up', (e) => {
  console.log('Yukari yonde hareket')
})

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

// Dinlemeyi birak
unsub()

Parametreler:

Alan	Tip	Zorunlu	Aciklama
code	string	Evet	Dinlenecek event kodu
handler	function	Evet	Callback fonksiyonu

Donus Tipi: () => void — dinlemeyi durduran fonksiyon

Event Nesnesi:

Alan	Tip	Aciklama
code	string	Event kodu (ornegin 'fire', 'up', 'idle')
type	string	'press', 'release' veya 'move'
timestamp	number	Milisaniye cinsinden zaman damgasi

Joystick Yon Kodlari: up, down, left, right, up_left, up_right, down_left, down_right, idle

---

controls.onAny

Tum kontrol event'lerini tek bir handler ile dinler.

JavaScript

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

---

controls.hide

Kontrolleri ekrandan kaldirir ama event listener'lari korur. Tekrar show() ile gosterilebilir.

JavaScript

gameTegra.controls.hide()

---

controls.destroy

Kontrolleri tamamen yok eder — DOM, CSS ve tum listener'lar temizlenir.

JavaScript

gameTegra.controls.destroy()

---

Custom Elements

SDK yuklendiginde <gametegra-joystick> ve <gametegra-buttons> custom element'leri otomatik kayit edilir. HTML icinde dogrudan kullanilabilir.

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

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

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

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

Custom element'ler ayni event sistemini kullanir — gameTegra.controls.on() ile dinlenebilir.

Multi-Touch

Joystick ve butonlar ayni anda kullanilabilir. Her biri bagimsiz touch identifier takip eder.

Target Modu

target parametresi verildiginde kontroller fixed overlay yerine belirtilen HTML element'in icine render edilir. Bu sayede oyun alaninin belirli bir bolgesine yerlestirebilirsiniz.

---

Tam Ornek

// Kontrolleri goster
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,
})

// Yonleri dinle
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())

// Butonlari dinle
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()
})

// Tum event'leri logla
gameTegra.controls.onAny((e) => {
  console.log(`[${e.code}] ${e.type}`)
})

// Oyun bittiginde temizle
gameTegra.controls.destroy()

D-Pad ile Basit Ornek

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()
})