Golix geliştirici rehberi

golix.js ile Node'dan Golix odası aç, odada olanları script'le, odalara bot olarak katıl ve kendi stadyumlarını yaz.

Başlarken

golix.js Node 22 veya üstünü ister.

npm install golix.js

Oda herkese açık lobiye kaydolur. Oyuncular senin sürecine doğrudan WebRTC ile bağlanır; doğrudan bağlantı kurulamazsa lobi üzerinden.

const golix = require('golix.js');

golix().then((HBInit) => {
  const room = HBInit({
    roomName: 'Odam',
    maxPlayers: 12,
    noPlayer: true,
    lobby: 'wss://golix.cosmosfutsal.com',
    // A-Z, a-z, 0-9, - ve _ ile 22 karakter: yeniden başlatmalarda oda linki aynı kalır.
    roomSecret: process.env.ROOM_SECRET,
    // Sadece bu roomSecret ile oda ilk kez açılırken: https://golix.cosmosfutsal.com/headlesstoken adresinden
    token: process.env.ROOM_TOKEN,
  });
  room.onRoomLink = (link) => console.log(link);
  room.onPlayerJoin = (player) => room.sendAnnouncement(`Hoş geldin ${player.name}`, player.id);
});

ES modülleriyle: import golix from 'golix.js'; const HBInit = await golix();

Callback'ler odanın tick'i içinde, saniyede 60 kez çalışır. İçlerinden çağrılan metotlar bir sonraki tick'te etkili olur. Bir callback hata fırlatırsa hata loglanır, oda durmaz.

Oda ayarları

AlanAnlamı
roomNameEn fazla 40 karakter.
playerNameHost oyuncusunun adı; noPlayer: true ile host oyuncusu olmaz.
passwordEn fazla 30 karakter.
maxPlayers2 ile 30 arası, varsayılan 12.
publicOda listede görünsün mü. Varsayılan true.
geoOda listesinde gösterilen { code, lat, lon }.
noPlayerOdayı host oyuncusu olmadan çalıştırır.
lobbyKaydolunacak ws:// ya da wss:// lobi adresi.
roomSecretlobby ile: oda kimliğinin türetildiği gizli anahtar; link yeniden başlatmalarda aynı kalır.
tokenlobby ile: bir roomSecret ilk kez oda açarken gereken, /headlesstoken sayfasından alınan oda token'ı. Bir kez ve on dakika geçerlidir; aynı roomSecret odayı sonra token'sız yeniden açar.
serverlobby olmadan: odayı kendi lobinden sun; çalışan bir sunucu ya da onun ayarları (varsayılan port 8787).
clientUrlOda linkinde kullanılan adres.
webrtcOyuncuların sürecine açtığı WebRTC bağlantıları için { bindAddress, portRange: [ilk, son], iceServers }.

Oda metotları

Oyuncular ve sohbet

MetotNot
sendChat(message, targetId?)Host oyuncusu olarak; en fazla 140 karakter.
sendAnnouncement(msg, targetId?, color?, style?, sound?)Stil normal, bold, italic, small, small-bold ya da small-italic; ses 0, 1 ya da 2; en fazla 1000 karakter.
setPlayerAdmin(id, admin)
setPlayerTeam(id, team)0 izleyici, 1 kırmızı, 2 mavi.
kickPlayer(id, reason, ban)Ban, oyuncunun auth'unu ve conn'unu kapsar.
clearBan(id), clearBans()
getPlayer(id), getPlayerList()
reorderPlayers(ids, moveToTop)
setPlayerAvatar(id, avatar)Null, oyuncunun kendi seçtiği avatarı geri verir.

Oyun

MetotNot
startGame(), stopGame(), pauseGame(paused)
setScoreLimit(n), setTimeLimit(minutes)0 ile 99 arası; sadece maçlar arasında.
setTeamsLock(locked)
setTeamColors(team, angle, textColor, colors)En fazla beş şerit.
setKickRateLimit(min, rate, burst)
getScores(), getBallPosition()scores.timeLimit saniye cinsindendir.
setCustomStadium(text)Bir stadyum dosyası alır; geçerli değilse hata fırlatır.
setDefaultStadium(name)Hazır stadyumlar: Standard, Wide Goals, Compact, Stadium, Oval, Rink, Big Rink, Stadium Wide Goals, Big Oval, Colossal. Classic, Easy, Small, Big, Rounded, Hockey, Big Hockey, Big Easy, Big Rounded ve Huge sırasıyla aynılarını gösterir.
startRecording(), stopRecording()Bir .glx tekrarını Uint8Array olarak döndürür.
setPassword(pass)Null ya da boş metin şifreyi kaldırır.

Diskler

MetotNot
getDiscCount()Önce stadyum diskleri (top 0'da), sonra oyuncu diskleri.
getDiscProperties(index), setDiscProperties(index, props)Alanlar x y xspeed yspeed xgravity ygravity radius bCoeff invMass damping color cMask cGroup; ondalıklar 32 bit olarak saklanır.
getPlayerDiscProperties(id), setPlayerDiscProperties(id, props)Oyunculara her kickoff'ta yeni disk verilir, değişiklik o zamana kadar sürer. Kalıcı değişiklik için setPlayerPhysics'i kullan.
Oyunculara gönderilemeyecek bir değerle yapılan çağrı (32 biti aşan bir renk, ondalıklı bir bayrak ya da 3 numaralı takım gibi) odayı bozmak yerine konsola bir uyarı yazılarak düşürülür.

Koruma

MetotNot
setRequireRecaptcha(on)Katılan herkesten captcha ister. Bkz. oda koruması.
setRaidProtection({ joins, seconds, minutes })Otomatik istila korumasını ayarlar; null kapatır.
setMaxPlayersPerConn(n)Tek bir ağ adresinden odada en fazla kaç oyuncu olabileceği; null sınırsız (varsayılan).

Oda olayları

Özelliğe bir fonksiyon ata.

OlayNot
onPlayerJoin(player), onPlayerLeave(player)
onPlayerChat(player, message)false döndürürsen mesaj diğerlerine gitmez.
onPlayerKicked(player, reason, ban, byPlayer)
onPlayerAdminChange(player, byPlayer), onPlayerTeamChange(player, byPlayer)
onPlayerActivity(player)Oyuncu girdi gönderdi; bu, tuşları değiştiğinde olur.
onPlayerInput(player, prevInput)Oyuncunun tuşları değişti; yenileri player.input'ta.
onPlayerAction(player, actionId, isPressed)setActionKeys(true) açık odalarda 1–6 arası bir aksiyon tuşuna basıldı ya da bırakıldı.
onPlayerBallKick(player)
onTeamGoal(team), onTeamVictory(scores)
onGameStart(byPlayer), onGameStop(byPlayer)
onGamePause(byPlayer), onGameUnpause(byPlayer)
onGameTick()Devam eden ve duraklatılmamış bir maçın her tick'inde.
onPositionsReset()Golden sonra, bir sonraki kickoff'tan önce.
onStadiumChange(name, byPlayer)
onKickRateLimitSet(min, rate, burst, byPlayer), onTeamsLockChange(locked, byPlayer)
onCollisionDiscVsDisc(disc1, disc2)İki disk birbirine çarpıp sekti; disk indeksleri getDiscProperties'teki gibi.
onCollisionDiscVsPlane(disc, planeIndex), onCollisionDiscVsSegment(disc, segmentIndex), onCollisionDiscVsVertex(disc, vertexIndex)Bir disk stadyumun o indeksteki plane'inden, segmentinden ya da vertex'inden sekti.
onRoomLink(url)Oda kaydolunca linki.
onLobbyDisconnect(retryInMs)Lobiye ulaşılamıyor. WebRTC'deki oyuncular oynamaya devam eder; lobi dönene kadar yeni oyuncu giremez.
onLobbyReconnect()Aynı oda linkiyle yeniden kaydolundu.

Direkten dönen top, topun (disk 0) direğin disk indeksiyle çarpışmasıdır; topa dokunuş, topun bir oyuncunun diskiyle çarpışmasıdır.

Oyuncu nesnesi

AlanAnlamı
id, name, team, admin
position{ x, y }; diski yoksa null.
inputBasılı tuşlar, girdi bayrakları olarak.
authOyuncunun kimliği: tarayıcısında kalan, 87 karakterlik base64url P-256 açık anahtarı. Sadece onPlayerJoin'de dolu gelir.
connOyuncunun ağ adresinin hex hali. Sadece onPlayerJoin'de dolu gelir.

Oyunu özelleştirme

Tek oyuncunun fiziği

room.setPlayerPhysics(player.id, { kickStrength: 7, acceleration: 0.12, radius: 17 });
room.getPlayerPhysics(player.id); // { kickStrength: 7, acceleration: 0.12, radius: 17 }
room.setPlayerPhysics(player.id, null); // stadyumunkine geri döner

radius bCoef invMass damping acceleration kickingAcceleration kickingDamping kickStrength kickback alanlarından istediklerin; vermediklerin stadyumun playerPhysics değerinde kalır. Değişiklik sen temizleyene kadar kickoff'lar boyunca sürer.

Oyun ekranına yazı

room.setHudItem('skor', { text: '3 turun 2. turu', x: 0.5, y: 0.12, align: 'center', color: 0xffd34d, size: 22 });
room.clearHudItem('skor');

x ve y, yazıyı sol üstten başlayarak ekranın oranı olarak yerleştirir. Aynı id ile setHudItem çağırmak yazıyı değiştirir. En fazla 100 karakterlik 16 yazı, boyut 8 ile 64 arası. Sonradan katılan oyuncular da görür.

Kamera

room.setCamera({ playerId: scorer.id }, 1.6); // bir oyuncuyu takip et, yakınlaştırarak
room.setCamera({ discIndex: 0 });              // top
room.setCamera({ x: 0, y: 0 }, 0.8);           // sabit bir nokta
room.setCamera(null);                          // normale dön

0,25 ile 4 arasındaki zoom, her oyuncunun kendi görüş ayarıyla çarpılır.

Formalar

setPlayerColors(id, angle, textColor, colors) bir oyuncuya takımınki yerine en fazla beş şeritli kendi formasını giydirir; clearPlayerColors(id) çıkarır.

Aksiyon tuşları

setActionKeys(true), oyuncuların altı ek tuş göndermesine izin verir; varsayılanları Q, E, R, F, C ve V. Her basış ve bırakış onPlayerAction(player, actionId, isPressed) olarak gelir; tuşların kendiliğinden bir etkisi yoktur.

Tarayıcıda oda açan host'lar bunların çoğunu kod yazmadan, odalarındaki Mods düğmesinden kullanabilir.

Bayraklar

room.InputFlags      // up 1, down 2, left 4, right 8, kick 16
room.CollisionFlags  // ball 1, red 2, blue 4, redKO 8, blueKO 16, wall 32, all 63,
                     // kick 64, score 128, c0 1<<28, c1 1<<29, c2 1<<30, c3 1<<31

Aksiyon tuşları açıkken player.input, 1–6 numaralı aksiyonları 32, 64, 128, 256, 512 ve 1024 bitleri olarak da taşır.

Oyuncu olarak katılmak

const { session, auth, key } = await golix.joinRoom({
  room: 'https://golix.cosmosfutsal.com/play?c=<id>',
  name: 'bot',
});
session.send({ type: 'chat', text: 'selam' });
session.onEvent((event) => console.log(event));

key'i sakla ve aynı auth ile tekrar girmek için key olarak geri ver. Reddedilen katılım, reason'ı password, full, banned, invalid, rateLimited, captcha, connLimit, version (oda başka bir Golix sürümü çalıştırıyor) ya da closed olan bir golix.JoinError ile sonuçlanır. Odada zaten bulunan bir anahtarla tekrar girmek eski bağlantının yerine geçer.

Tekrarlar

golix.decodeReplay(bytes), golix.encodeReplay(replay) ve golix.trimReplay(replay, fromFrame, toFrame), .glx tekrarlarını okur, yazar ve keser. Oyun saniyede 60 kare çalışır; f karesinde biten 10 saniyelik klip trimReplay(replay, f - 600, f)'dir. Tekrarlar oyunda oda listesinden açılır.

Stadyum dosyaları

Stadyum, tek bir nesne içeren JSON5 metin dosyasıdır (.hbs). name, width ve height dışındaki her alanın varsayılanı vardır; null yazmak alanı hiç yazmamakla aynıdır.

AlanAnlamı
nameOdada görünen ad.
width, heightKameranın içinde kaldığı alanın yarı boyutu.
maxViewWidthEkran bu genişlikten fazlasını gösterecekse yakınlaştırır; 0 (varsayılan) sınırsız.
cameraFollow"ball" (varsayılan) topu ve oyuncuyu, "player" sadece oyuncuyu takip eder.
spawnDistanceSpawn noktası yoksa takımların kickoff'ta merkeze olan uzaklığı. Varsayılan 200.
redSpawnPoints, blueSpawnPoints[[x, y], ...] kickoff konumları, oyuncu sırasıyla dağıtılır; maç sırasında takıma giren oyuncu sonuncusunu alır.
kickOffReset"partial" (varsayılan) kickoff'ta topu ve oyuncuları, "full" bütün diskleri sıfırlar.
canBeStoredOyuncular stadyumu kaydedebilir mi. Varsayılan true.
bg{ type, width, height, kickOffRadius, cornerRadius, goalLine, color }; type "grass", "hockey" ya da "none" (varsayılan), renk varsayılanı "718C5A".
traitsAdlandırılmış varsayılan alan grupları; "trait": "ad" yazan bir nesne, vermediği alanları o gruptan alır.
vertexes{ x, y, bCoef, cMask, cGroup }: disklerin sektiği noktalar.
segments{ v0, v1, curve, curveF, bias, bCoef, cMask, cGroup, vis, color }: iki vertex arasındaki çizgiler. curve çizgiyi o kadar derece büker; bias çizgiyi tek taraflı ve o kalınlıkta yapar.
planes{ normal: [x, y], dist, bCoef, cMask, cGroup }: sonsuz duvarlar, genelde dış sınırlar.
goals{ p0: [x, y], p1: [x, y], team }: score bayraklı bir disk geçince diğer takıma gol yazan çizgi.
discs{ pos, speed, gravity, radius, invMass, damping, bCoef, color, cMask, cGroup }: direkler, ek toplar ve yuvarlak olan her şey. invMass: 0 olan disk hareket etmez.
joints{ d0, d1, length, strength, color }: iki diski birbirine bağlar. length null başlangıçtaki uzaklığı korur, sayı onu sabitler, [min, max] bir aralığa izin verir; strength "rigid" (varsayılan) ya da yay için bir sayı.
playerPhysics{ radius, bCoef, invMass, damping, acceleration, kickingAcceleration, kickingDamping, kickStrength, kickback, gravity, cGroup }.
ballPhysicsTop için bir disk (top her zaman gol atar ve vurulabilir) ya da ilk diski top yapmak için "disc0".

Oda koruması

Her oda, hiç kod yazmadan şunlara sahiptir:

Captcha, Cloudflare Turnstile'dır. setRequireRecaptcha(true) onu kalıcı olarak açar. Turnstile anahtarı olmayan bir lobide hem bu ayar hem istila koruması, adres başına 30 saniyede bir katılma denemesine izin verir.