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ı
| Alan | Anlamı |
|---|---|
roomName | En fazla 40 karakter. |
playerName | Host oyuncusunun adı; noPlayer: true ile host oyuncusu olmaz. |
password | En fazla 30 karakter. |
maxPlayers | 2 ile 30 arası, varsayılan 12. |
public | Oda listede görünsün mü. Varsayılan true. |
geo | Oda listesinde gösterilen { code, lat, lon }. |
noPlayer | Odayı host oyuncusu olmadan çalıştırır. |
lobby | Kaydolunacak ws:// ya da wss:// lobi adresi. |
roomSecret | lobby ile: oda kimliğinin türetildiği gizli anahtar; link yeniden başlatmalarda aynı kalır. |
token | lobby 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. |
server | lobby olmadan: odayı kendi lobinden sun; çalışan bir sunucu ya da onun ayarları (varsayılan port 8787). |
clientUrl | Oda linkinde kullanılan adres. |
webrtc | Oyuncuların sürecine açtığı WebRTC bağlantıları için { bindAddress, portRange: [ilk, son], iceServers }. |
Oda metotları
Oyuncular ve sohbet
| Metot | Not |
|---|---|
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
| Metot | Not |
|---|---|
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
| Metot | Not |
|---|---|
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. |
Koruma
| Metot | Not |
|---|---|
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.
| Olay | Not |
|---|---|
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
| Alan | Anlamı |
|---|---|
id, name, team, admin | |
position | { x, y }; diski yoksa null. |
input | Basılı tuşlar, girdi bayrakları olarak. |
auth | Oyuncunun kimliği: tarayıcısında kalan, 87 karakterlik base64url P-256 açık anahtarı. Sadece onPlayerJoin'de dolu gelir. |
conn | Oyuncunun 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.
| Alan | Anlamı |
|---|---|
name | Odada görünen ad. |
width, height | Kameranın içinde kaldığı alanın yarı boyutu. |
maxViewWidth | Ekran 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. |
spawnDistance | Spawn 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. |
canBeStored | Oyuncular 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". |
traits | Adlandı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 }. |
ballPhysics | Top için bir disk (top her zaman gol atar ve vurulabilir) ya da ilk diski top yapmak için "disc0". |
- Renkler
"RRGGBB",[r, g, b]ya da"transparent"olur. Şeffaf bir diskin dış çizgisi yine görünür; şeffaf bir segment,visfalse değilse beyaz çizilir. - Çarpışma bayrakları ad listeleridir:
["ball", "red", "c0"]. İki nesne, her birinincGroup'u diğerinincMask'ıyla en az bir bayrak paylaştığında çarpışır. - Varsayılanlar: vertex, segment ve plane'lerde
bCoef1,cGroupwall vecMaskall; disklerde yarıçap 10,invMass1, damping 0,99,bCoef0,5, renk beyaz,cGroupvecMaskall. - Sınırlar: vertex, segment, plane, kale ve joint'ten her birinden 255, top dahil 255 disk ve dosya başına bir milyon karakter. Yanlış tipte bir alan (metin olarak yazılmış bir sayı gibi) dosyayı geçersiz kılar.
- Top ve stadyum diskleri oyuncuların üstüne çizilir.
Oda koruması
Her oda, hiç kod yazmadan şunlara sahiptir:
- Tek bir adres lobiye aynı anda 30 bağlantı açabilir, 10 saniyede en fazla 30 yeni bağlantı kurabilir.
- Tek bir adresin her odaya dakikada 5 katılma denemesi hakkı vardır.
- Saniyede 300'den fazla mesaj gönderen bağlantı atılır ve bir dakika içeri giremez.
- Sohbet oyuncu başına hız sınırlıdır.
- İstila koruması. 10 saniye içinde yeni anahtarlı 6 oyuncu girerse oda, 5 dakika boyunca her yeni gelenden captcha ister ve bunu duyurur. Odanın ilk 2 dakikası ve daha önce girmiş anahtarlar sayılmaz; böylece yeniden başlayan bir oda, koruma devreye girmeden dolabilir.
- Bir kez captcha çözen oyuncu, tarayıcısının anahtarına bağlı bir kanıt alır ve 30 gün boyunca hiçbir odada captcha çözmez. Her girişte yeni anahtar üreten istilacılar her seferinde çözer.
- Oda açmak bir kez captcha ister: Create Room düğmesinden ya da script için /headlesstoken sayfasından alınan token'la.
roomSecret'ı ile geri dönen oda token istemez. - Golix yöneticileri bir kimliği tek seferde bütün odalardan banlayabilir; o kimlik katılırken reddedilir ve içinde bulunduğu odalardan atılır.
kickPlayerile verilen banlar sadece o odada geçerlidir.
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.