Game dev

Cum am construit Neon Arcade: jocuri 3D în browser livrate pe web și mobil dintr-un singur codebase

Publicat 25 aprilie 2026 · 7 min citire

Neon Arcade este colecția noastră de jocuri gratuite în browser, găzduită la games.hashcoreai.com. În momentul scrierii acestui devlog conține trei jocuri 3D originale, toate construite în casă la HashCoreAI:

Tidefall — un platformer într-o mlaștină bioluminescentă, combinat cu un colony builder: ataci, construiești, aperi.
Planet Surfer — un endless runner spațial neon: navighezi prin cosmos, eviți obstacolele, supraviețuiești.
Barrel Brigade — un shooter arcade pe trei benzi: conduci echipa, spargi butoaiele.

Toate trei rulează în orice browser modern și, în același timp, în aplicațiile native pentru iOS și Android — din exact același cod. Acest articol explică deciziile de arhitectură care fac posibil acest lucru, inclusiv compromisurile pe care nu le-am evitat.

Stack-ul: Three.js + Vite + TypeScript

Fiecare joc este o aplicație web independentă: Three.js pentru randarea 3D pe WebGL, Vite pentru bundling și dev server, TypeScript pentru tot codul de joc. Hub-ul arcade — grila de carduri pe care alegi un joc — este o a patra aplicație Vite + TypeScript, separată de jocuri.

Le ținem deliberat separate. Fiecare joc are propriul package.json, propriul vite.config.ts și propriul build. Asta înseamnă că un bug de dependență din Tidefall nu poate dărâma Planet Surfer, iar fiecare joc poate evolua în ritmul lui. La build, un script de assembly (scripts/assemble.mjs) copiază hub-ul construit în rădăcină și fiecare joc construit sub propriul sub-path, producând un singur folder public/ pe care îl deployăm pe Firebase Hosting.

Componentă	Servită la	Build
Hub arcade	games.hashcoreai.com/	Vite + TS + Capacitor
Planet Surfer	/planet-surfer/	Three.js + Vite
Barrel Brigade	/barrel-brigade/	Three.js + Vite
Tidefall	/tidefall/	Three.js + Vite

Un detaliu mic dar important: fiecare joc se construiește cu base: './' în Vite. Asta face ca toate path-urile către asset-uri să fie relative, deci același build rulează corect la /tidefall/ pe hub, dar și dintr-un wrapper file:// sau dintr-un sub-path complet diferit. Nu trebuie să recompilăm un joc doar pentru că s-a schimbat originea care îl servește.

Decizia cheie: în aplicația nativă, jocurile se încarcă din web-ul live

Aceasta este decizia de arhitectură care definește întregul proiect. Aplicațiile native sunt construite cu Capacitor, care împachetează un build web într-un shell nativ iOS/Android cu o punte (bridge) către API-uri native.

Abordarea evidentă ar fi să împachetezi toate jocurile în interiorul aplicației. Noi am ales contrariul. Doar hub-ul este împachetat în aplicație; jocurile se încarcă din originea web live, https://games.hashcoreai.com/<id>/, chiar și înăuntrul aplicației native. În capacitor.config.ts permitem navigarea către acel domeniu, iar codul nostru de platformă decide URL-ul:

Pe web folosim path-uri relative same-origin. În aplicația nativă, jocurile se încarcă din aceeași origine web live. Câștigul: a adăuga un joc = deploy pe Firebase și apare instant în aplicație. Fără bundling, fără update în magazin, niciodată.

Concret, fluxul de adăugare a unui joc nou arată așa:

Pui jocul în games/<id>/ și îl adaugi în scriptul de assembly.
Îl adaugi în lista de jocuri (games.json, servit de pe domeniul web).
Rulezi npm run deploy.

Atât. Web-ul și aplicațiile native deja instalate pe telefoanele oamenilor îl preiau — fără update în App Store sau Google Play. Hub-ul nu are jocurile în cod la momentul build-ului: la pornire face fetch la lista live de jocuri și o afișează. Lista împachetată în aplicație este doar un fallback offline.

De ce o singură origine web partajată

O singură origine ne dă trei lucruri gratis. Un singur cont Firebase și o singură sesiune de autentificare funcționează în toate jocurile, fiindcă rulează pe același domeniu. Un singur portofel de tokenuri este consistent peste tot. Și o singură conductă de deploy livrează simultan pe toate platformele. Costul de mentenanță al unui joc nou se apropie de zero din punct de vedere al distribuției.

Compromisul WebView vs. nativ

Această abordare nu este gratuită. Iată ce am cântărit, sincer:

Aspect	Jocuri în web live (alegerea noastră)	Jocuri împachetate nativ
Joc nou	Deploy web, apare instant	Update în magazin (zile de review)
Offline	Necesită conexiune (mitigat prin cache)	Funcționează offline
Performanță	WebGL în WebView	WebGL în WebView (identic)
Mărime aplicație	Mică (doar shell-ul)	Crește cu fiecare joc
Risc de respingere în magazin	Necesită valoare nativă reală	Mai puțin risc

Cel mai important compromis: o aplicație care e „doar un site împachetat” riscă respingerea pe motiv de „minimum functionality”, mai ales pe App Store. De aceea am adăugat valoare nativă reală în shell, activată doar pe native și încărcată dinamic ca să nu afecteze build-ul web: bara de stare colorată în tema neon, butonul hardware de back pe Android care merge prin istoricul in-app (nu lasă utilizatorul într-un dead-end), blocarea orientării per joc (Tidefall pornește mereu landscape, restul portrait), feedback haptic la atingeri și o notificare locală de re-engagement programată local, fără server.

Performanța pe telefoane Android ieftine

WebGL prin WebView rulează la fel ca un joc web obișnuit — nu primești magie nativă gratis. Pe dispozitive de gamă joasă, GPU-ul și lățimea de bandă a memoriei sunt constrângerea reală, nu JavaScript-ul. Lecțiile noastre practice:

Buget de draw calls, nu doar de poligoane. Pe GPU-uri mobile ieftine, numărul de draw calls și schimbările de stare dor mai mult decât numărul brut de triunghiuri. Comasăm geometriile și instanțiem obiectele repetate.
Țintă es2022 la build. Compilăm pentru un baseline modern, ca să nu plătim transpilare inutilă, păstrând în același timp compatibilitatea cu WebView-urile actuale.
Particule și efecte neon ieftine. Estetica neon vine din shadere și bloom controlat, nu din geometrie densă. Arată scump, costă puțin.
Degradare elegantă. Mai bine un framerate stabil cu efecte reduse decât stuttering la efecte maxime.

Strategia de încărcare și de asset-uri

Pentru că jocurile se încarcă din rețea, cache-ul HTTP este critic. Configurăm header-ele pe Firebase Hosting astfel:

HTML-ul se servește cu no-cache, deci un deploy nou se vede imediat.
Fișierele cu hash din assets/ și modelele .glb, plus fonturile woff/woff2, primesc max-age=31536000, immutable — un an, cacheabile pentru totdeauna.

Combinația dă ce ne dorim: actualizările apar instant, dar asset-urile grele 3D se descarcă o singură dată și apoi vin din cache. Hub-ul deține și PWA-ul (service worker-ul); jocurile nu înregistrează service workere proprii, ca să nu se lupte pe scope. La nivel de cod, SDK-urile grele (RevenueCat, de exemplu) sunt importate dinamic abia când sunt necesare, ca să țină pornirea ușoară.

Un cont, un portofel — server-authoritative

Un singur proiect Firebase deservește tot. Utilizatorii se autentifică o singură dată cu Google, Apple sau email și au același cont pe web, Android și iOS. Pe native, signInWithPopup nu funcționează în WebView, așa că rulăm fluxul nativ de provider și apoi semnăm credențialul în SDK-ul Firebase JS — astfel întreaga aplicație împarte o singură sesiune de autentificare.

Peste cont stă un portofel de tokenuri partajat între jocuri, stocat în Firestore. Punctul cheie de design este că este server-authoritative: regulile noastre Firestore permit clientului doar să citească propriul portofel; orice scriere a soldului este interzisă din client și se face exclusiv din Cloud Functions cu Admin SDK. Clientul se abonează la soldul live și reflectă schimbările în UI, dar nu poate inventa tokenuri.

Notă: tokenurile sunt valută pur virtuală în jocuri. Nu sunt bani reali, nu pot fi „câștigați” ca venit și nu există nicio componentă de investiție — sunt doar design de joc, ca monedele din orice joc clasic.

Ce am învăța

Separarea jocurilor de shell și încărcarea lor din web-ul live a fost decizia care a plătit cel mai mult. Eliberează echipa de ciclul de review din magazine pentru orice e conținut, păstrând în același timp un strat nativ subțire pentru lucrurile care chiar au nevoie de el. Compromisul — dependența de rețea — îl gestionăm cu o politică de cache disciplinată. Pentru un studio mic care publică multe jocuri mici, este exact echilibrul corect.

Vrei să le încerci? Toate jocurile sunt gratuite la games.hashcoreai.com. Iar dacă plănuiești o aplicație web sau mobilă care trebuie să livreze rapid pe mai multe platforme dintr-un singur codebase, scrie-ne la contact@hashcoreai.com — exact genul de arhitectură pe care o construim pentru clienți.

Neon Arcade is our collection of free browser games, hosted at games.hashcoreai.com. As of this devlog it holds three original 3D games, all built in-house at HashCoreAI:

Tidefall — a bioluminescent swamp platformer fused with a colony builder: raid, build, defend.
Planet Surfer — an endless neon space-runner: surf the cosmos, dodge, survive.
Barrel Brigade — a three-lane arcade shooter: steer the squad, pop the barrels.

All three run in any modern browser and, at the same time, inside the native iOS and Android apps — from the exact same code. This article explains the architecture decisions that make that possible, including the trade-offs we did not dodge.

The stack: Three.js + Vite + TypeScript

Each game is a standalone web app: Three.js for WebGL 3D rendering, Vite for bundling and the dev server, TypeScript for all the game code. The arcade hub — the grid of cards where you pick a game — is a fourth Vite + TypeScript app, separate from the games.

We keep them deliberately separate. Every game has its own package.json, its own vite.config.ts and its own build. That means a dependency bug in Tidefall can't knock over Planet Surfer, and each game can evolve at its own pace. At build time an assembly script (scripts/assemble.mjs) copies the built hub to the root and each built game under its own sub-path, producing a single public/ folder we deploy to Firebase Hosting.

Component	Served at	Build
Arcade hub	games.hashcoreai.com/	Vite + TS + Capacitor
Planet Surfer	/planet-surfer/	Three.js + Vite
Barrel Brigade	/barrel-brigade/	Three.js + Vite
Tidefall	/tidefall/	Three.js + Vite

One small but important detail: each game builds with base: './' in Vite. That makes every asset path relative, so the same build runs correctly at /tidefall/ on the hub, but also from a file:// wrapper or an entirely different sub-path. We never have to rebuild a game just because the origin serving it changed.

The key decision: in the native app, games load from the live web

This is the architecture decision that defines the whole project. The native apps are built with Capacitor, which wraps a web build in a native iOS/Android shell with a bridge to native APIs.

The obvious approach is to bundle every game inside the app. We did the opposite. Only the hub is bundled into the app; the games load from the live web origin, https://games.hashcoreai.com/<id>/, even inside the native app. In capacitor.config.ts we allow navigation to that domain, and our platform code decides the URL:

On the web we use same-origin relative paths. In the native app the games load from the same live web origin. The win: adding a game = deploy to Firebase and it appears in the app instantly. No bundling, no app update, ever.

Concretely, the flow to add a new game looks like this:

Drop the game into games/<id>/ and add it to the assembly script.
Add it to the game list (games.json, served from the web domain).
Run npm run deploy.

That's it. The web and the native apps already installed on people's phones pick it up — no App Store or Google Play update. The hub doesn't hard-code the games at build time: on startup it does a fetch of the live game list and renders it. The list bundled into the app is only an offline fallback.

Why a single shared web origin

One origin buys us three things for free. A single Firebase account and a single auth session work across all games, because they run on the same domain. A single token wallet is consistent everywhere. And a single deploy pipeline ships to every platform at once. The maintenance cost of a new game, from a distribution standpoint, approaches zero.

The WebView vs. native trade-off

This approach is not free. Here is what we weighed, honestly:

Aspect	Games on the live web (our choice)	Games bundled natively
New game	Web deploy, appears instantly	Store update (days of review)
Offline	Needs a connection (mitigated by cache)	Works offline
Performance	WebGL in a WebView	WebGL in a WebView (identical)
App size	Small (shell only)	Grows with every game
Store-rejection risk	Needs real native value	Lower risk

The biggest trade-off: an app that is "just a wrapped website" risks rejection on minimum-functionality grounds, especially on the App Store. So we added genuine native value to the shell, gated to native only and dynamically imported so the plain web build never loads it: neon-themed status-bar styling, the Android hardware back button that walks the in-app history (never stranding the user in a dead-end), per-game orientation locking (Tidefall always starts landscape, the rest portrait), haptic feedback on taps, and a re-engagement local notification scheduled on-device with no server.

Performance on cheap Android phones

WebGL through a WebView performs like any ordinary web game — you get no free native magic. On low-end devices, the GPU and memory bandwidth are the real constraint, not JavaScript. Our practical lessons:

Budget draw calls, not just polygons. On cheap mobile GPUs, the number of draw calls and state changes hurts more than raw triangle count. We batch geometry and instance repeated objects.
Target es2022 at build. We compile for a modern baseline so we don't pay needless transpilation, while staying compatible with current WebViews.
Cheap particles and neon effects. The neon look comes from shaders and controlled bloom, not dense geometry. It reads as expensive and costs little.
Graceful degradation. A steady framerate with reduced effects beats stutter at maximum effects.

Loading and asset strategy

Because the games load over the network, HTTP caching is critical. We set the headers on Firebase Hosting like this:

HTML is served with no-cache, so a fresh deploy is seen immediately.
Hashed files under assets/ and the .glb models, plus woff/woff2 fonts, get max-age=31536000, immutable — one year, cacheable forever.

That combination gives us exactly what we want: updates appear instantly, but heavy 3D assets download once and then come from cache. The hub also owns the PWA (the service worker); the games don't register their own service workers so they can't fight over scope. At the code level, heavy SDKs (RevenueCat, for example) are dynamically imported only when needed, to keep startup light.

One account, one wallet — server-authoritative

A single Firebase project serves everything. Users sign in once with Google, Apple or email and have the same account on web, Android and iOS. On native, signInWithPopup doesn't work inside the WebView, so we run the native provider flow and then sign that credential into the Firebase JS SDK — so the whole app shares one auth session.

On top of the account sits a token wallet shared across games, stored in Firestore. The key design point is that it is server-authoritative: our Firestore rules let the client only read its own wallet; any write to the balance is denied from the client and happens exclusively in Cloud Functions with the Admin SDK. The client subscribes to the live balance and reflects changes in the UI, but it cannot mint tokens.

Note: tokens are purely virtual in-game currency. They are not real money, they cannot be "earned" as income, and there is no investment component — it's just game design, like coins in any classic arcade game.

What we learned

Separating the games from the shell and loading them from the live web was the decision that paid off most. It frees the team from the store-review cycle for anything that is content, while keeping a thin native layer for the things that genuinely need it. The trade-off — the network dependency — we manage with a disciplined caching policy. For a small studio shipping many small games, that is exactly the right balance.

Want to try them? Every game is free at games.hashcoreai.com. And if you're planning a web or mobile app that needs to ship fast to multiple platforms from one codebase, write to us at contact@hashcoreai.com — this is exactly the kind of architecture we build for clients.