HTML5-game op uw website hosten: uploaden, insluiten, oplossen

Een HTML5-game hosten, in één zin: upload de inhoud van de map game/ naar een willekeurige webhost die statische bestanden serveert, laat de submappen precies zoals ze zijn en open het adres van de map in een browser. De hostklare map game/ van elke editie in onze marketplace draait ongewijzigd: geen PHP, geen database, geen buildstap en geen account, dus de host hoeft alleen bestanden aan de browser van de speler te geven.

Dat is het hele werk als alles goed gaat. Deze gids gaat over de andere dagen: een leeg scherm, 404-fouten, een MIME-type-melding, een iframe dat niets wil tonen. Wij verkopen deze templates, dus lees dit als veldhandleiding voor onze eigen pakketten. We serveerden kopieën van Gridspark en Velvet Pool vanaf een tijdelijke lokale server, braken Gridspark opzettelijk op meerdere manieren en lazen de openbare handleidingen van andere edities. Komt een bewering uit een handleiding in plaats van uit onze eigen test, dan zeggen we dat.

Wat een HTML5-game hosten in feite inhoudt

Een statische host slaat bestanden op en geeft ze op verzoek aan browsers. Hij voert uw game nooit uit; dat doet de browser van de speler. Daarom lezen de vereisten van onze edities zo eenvoudig: een actuele browser, een host die statische bestanden serveert via HTTP of HTTPS, en geen PHP, database of account om te spelen. De map game/ is al gebouwd, dus publiceren vraagt geen npm en geen buildstap.

Twee grenzen die u vooraf moet kennen. Sommige edities hebben optionele onderdelen die niet statisch zijn: Zabum en Ricopop noemen een optioneel klassement dat PHP 7.4 of nieuwer en een beschrijfbare map vraagt, en de TypeScript-edities (Beep Out, Pinloop, Trimora, Twirldrop, Riffvolt, Sunset Rally, Tenguin, Mochi Monsters, Deepforge, Barricade Z en Zabum) hebben alleen Node.js nodig als u de bron wilt bewerken en opnieuw bouwen; elke handleiding noemt de versie. Velvet Pool, Puttide, Ricopop en Gridspark worden geleverd als gewone JavaScript, zonder compilatiestap tussen uw wijzigingen en de bestanden die u uploadt. Niets daarvan is nodig om de game te publiceren zoals geleverd. En hosting zelf maakt geen deel uit van de aankoop. De winkelvoorwaarden noemen hosting en installatie op uw server onder de aparte diensten waarvoor we vóór aanvang een offerte geven; support dekt vragen over het installeren en gebruiken van de geleverde bestanden.

Wat omhoog gaat, en wat op uw computer blijft:

• Upload alles in game/: index.html, scripts, stijlen, afbeeldingen, geluiden en lettertypen.
• Laat source/ (de bewerkbare ontwikkelaarskopie), documentation/ (de handleiding) en de ZIP zelf weg. De handleiding van Zabum noemt het per ongeluk uploaden van source/ als oorzaak van 404-fouten zoals main.tsx.
• Bewaar de licentievermeldingen van derden die bij het pakket horen naast uw product, zoals de voorwaarden vragen.

Bekijk Gridspark, de editie die we als voorbeeld gebruiken

Een HTML5-game hosten: het korte pad van ZIP naar speelbare pagina

Deze stappen volgen de installatiehoofdstukken van de handleidingen van Velvet Pool, Puttide, Gridspark en Sunset Rally, plus de controles die we na het testen hebben toegevoegd. Gridspark is het voorbeeld, omdat dat de editie is die we het vaakst serveerden en braken.

1. Pak het pakket uit op uw computer. U vindt game/ (de map die u publiceert), source/ (de bewerkbare kopie) en documentation/ (de handleiding).
2. Optioneel maar goedkoop: test lokaal. Open een terminal in game/, voer python -m http.server 8765 uit en ga naar http://localhost:8765/. Speelt hij daar, dan zijn de bestanden goed en ligt elk later probleem bij de host.
3. Kies nu het definitieve adres, bijvoorbeeld https://your-site.example/games/gridspark/. Een submap werkt omdat de paden in de game relatief zijn; de handleiding van Gridspark stelt public_html/games/gridspark/ voor.
4. Upload de inhoud van game/ naar die map met de bestandsbeheerder van uw host of een FTP-client, en behoud elke submap. index.html moet direct in de map terechtkomen, niet een niveau dieper.
5. Open het adres van de map via https, met de slash aan het eind. In Gridspark tikt u op het startscherm (browsers wachten op een tik of klik voordat ze audio toestaan) en drukt u op Play.
6. Doe één zet, herlaad de pagina en controleer of het menu nu Continue aanbiedt. Dat bewijst dat de browser de voortgang voor uw adres bewaart.
7. Link vanaf uw site naar de map, of sluit hem in een pagina in (zie het onderdeel over iframes hieronder).

Een afgeronde Gridspark-map bevat index.html, style.css, gridspark.config.js, src/ en assets/ naast elkaar, en de handleiding vraagt u ze bij elkaar te houden. Andere edities zijn anders ingedeeld (Velvet Pool heeft css/ en assets/ in plaats van één stijlblad), maar de regel is dezelfde: upload de map zoals hij komt.

Waarom dubbelklikken op index.html een lege pagina geeft

De edities die we openden, laden hun code als ES-modules, en browsers weigeren modules te laden vanaf file://-adressen. We openden Gridspark rechtstreeks vanaf schijf in Chromium en kregen een donker, leeg scherm. De console meldde dat het script door het CORS-beleid werd geblokkeerd, met de reden "Cross origin requests are only supported for protocol schemes" zoals http en https. Dezelfde map, geserveerd door een lokale webserver, toonde meteen het startscherm. De handleidingen van Velvet Pool, Puttide, Sunset Rally en Gridspark zeggen allemaal hetzelfde: open de game niet vanaf file://.

• Werkt niet: file:///C:/Users/you/games/gridspark/index.html
• Werkt: http://localhost:8765/ vanaf een lokale testserver, of https://your-site.example/games/gridspark/ op uw host.

We testten alleen Chromium. De handleidingen beschrijven de blokkade als iets wat gangbare browsers doen, dus ga er overal van uit.

De game in een pagina insluiten met een iframe

Om de game binnen een bestaande pagina te tonen, wijst u een iframe naar de geüploade map. Dit is de tag die we testten:

<iframe src="https://your-site.example/games/gridspark/" title="Gridspark" allow="fullscreen; autoplay" width="960" height="540" style="border:0"></iframe>

• src: het volledige adres van de map, met https en de slash aan het eind.
• title: een korte naam. Schermlezers gebruiken hem om het frame te beschrijven.
• allow="fullscreen; autoplay": de handleidingen zeggen dat u volledig scherm en autoplay in een iframe moet toestaan wanneer nodig. In onze test had een frame van een ander adres zonder dit volledig scherm uitgeschakeld, en Gridspark verborg gewoon zijn knop voor volledig scherm. Het oudere attribuut allowfullscreen gaf hetzelfde resultaat als allow. Een frame op hetzelfde adres als de pagina krijgt hoe dan ook volledig scherm.
• Geen sandbox-attribuut. Met alleen sandbox="allow-scripts" startte Gridspark nooit: het frame krijgt een null-oorsprong, de browser blokkeerde het eigen script van de game en local storage gaf een beveiligingsfout. Met allow-same-origin erbij werkt het, maar MDN waarschuwt dat dit paar op een frame met dezelfde oorsprong de bescherming opheft, dus laat sandbox weg voor een game die u zelf host.

Maak het geschikt voor telefoons

Een vast 16:9-vak ziet er op een desktop goed uit en op een telefoon verkeerd. Bij een breedte van 390 px is een iframe met aspect-ratio 16/9 maar 219 px hoog, en het menu van Gridspark werd afgesneden onder de knop Daily challenge. Door het frame een hoogte van 75svh te geven, driekwart van de schermhoogte, was het hele menu zichtbaar. Ook uw eigen pagina heeft een viewport-metatag nodig; de zes pakketten die we openden hebben er allemaal een in hun eigen index.html, en daarom schaalt de game bij rechtstreeks openen.

De game werkt op zijn eigen adres zonder pagina eromheen, dus een gewone link die dat adres opent is altijd een geldige terugvaloptie.

Bekijk Velvet Pool, een 3D-editie die op dezelfde manier wordt ingesloten

WordPress en andere sitebouwers

De map hosten en hem op een pagina tonen zijn twee aparte klussen, en in WordPress gebruiken ze twee verschillende gereedschappen. Alles hieronder komt uit de WordPress-documentatie en de ontwikkelaarsreferentie, niet uit het zelf draaien van WordPress.

1. Upload de map met de bestandsbeheerder van uw host of via FTP in de mappenstructuur van de site (bijvoorbeeld een map games/ naast de WordPress-mappen). Niet via de Mediabibliotheek: de code van WordPress haalt .html en .js uit de toegestane uploadtypen tenzij de gebruiker de capability unfiltered_html heeft.
2. Open het adres van de map apart voordat u een pagina aanraakt. De standaard Apache-regels die WordPress documenteert, sturen een verzoek alleen naar index.php als er geen passend bestand of passende map bestaat (dat toetsen de voorwaarden !-f en !-d), dus een geüploade map wordt ongewijzigd geserveerd.
3. Voeg het iframe toe in een blok Aangepaste HTML. WordPress documenteert dat bij gebruikers zonder de capability unfiltered_html, bijvoorbeeld een Bijdrager, iframe-tags worden verwijderd wanneer het bericht wordt opgeslagen. Verdwijnt het frame na het opslaan, controleer dan wie de pagina heeft bewerkt.

Andere sitebouwers en CMS’en: die hebben we niet getest en we doen over geen van hen beweringen. De game heeft overal twee dingen nodig, een plek voor de geüploade map en een insluitelement dat een iframe accepteert. Biedt een bouwer geen van beide, host de map dan ergens waar statische bestanden worden geserveerd en link naar dat adres.

Als hij niet start: een lijst voor probleemoplossing

Open de ontwikkelaarstools van de browser (F12 in de meeste desktopbrowsers) en bekijk de tabbladen Console en Network voordat u iets wijzigt. Elke fout hieronder laat daar een rode regel achter, en de bestandsnaam erin wijst meestal naar de oorzaak.

Een leeg scherm

Controleer in deze volgorde: het adres begint met http:// of https://; de console heeft geen rode regels; bestandsnamen houden hun exacte hoofd- en kleine letters; en, voor de 3D-edities, WebGL2 is beschikbaar (de handleiding van Velvet Pool zegt hardwareversnelling in te schakelen). Linux-hosts behandelen Game.js en game.js als twee bestanden en Windows niet, dus een map die op uw pc werkte, kan na het uploaden breken. De handleidingen van Velvet Pool en Zabum waarschuwen er allebei voor.

404 voor src/main.js, lettertypen of afbeeldingen

Een deel van de map is niet aangekomen, of een niveau te diep terechtgekomen. We reproduceerden het door alleen index.html, style.css en het configuratiebestand te uploaden: het scherm bleef leeg en het tabblad Network toonde 404 voor src/main.js en elk lettertype. Upload de ontbrekende mappen, of verplaats de inhoud omhoog zodat index.html staat op het adres dat u opent. Ontbreken afbeeldingen of geluiden of zijn ze beschadigd, dan stelt de handleiding van Zabum voor FTP in binaire of automatische modus te gebruiken, of een ZIP te uploaden en die in de bestandsbeheerder van de host uit te pakken. Een 404 is een ontbrekend bestand. Het is geen MIME-probleem.

De pagina laadt zonder stijl, met reusachtige pictogrammen

Serveert een rewrite- of schone-URL-instelling de map zonder de slash aan het eind, dan worden relatieve paden een niveau hoger opgelost. We reproduceerden het met een testserver die de mappagina teruggeeft zonder te doorverwijzen. De browser vroeg om /games/style.css en /games/src/main.js in plaats van de bestanden in /games/gridspark/, kreeg 404’s en tekende het menu als kale knoppen en te grote pictogrammen. Link naar de map met de slash aan het eind, of wijs rechtstreeks naar index.html.

Een MIME-type-fout bij een modulescript

In onze test stond in de console: Failed to load module script: Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/plain". Browsers zijn streng voor modulescripts. De handleidingen zeggen dat de server .js-bestanden met een JavaScript-MIME-type moet sturen, en .wasm als application/wasm; de handleiding van Sunset Rally voegt .mjs toe. Het tabblad Network toont de Content-Type van elk bestand. In de builds die we openden, zijn de modules .js-bestanden. Voegt u zelf .mjs-bestanden toe en wijst een oudere Apache-configuratie ze niet toe, dan lost één regel in .htaccess het op, dezelfde die onze eigen site gebruikt:

AddType text/javascript .mjs

De typetabel van Apache 2.4.62 op onze testmachine wijst js en mjs al toe aan text/javascript en wasm aan application/wasm, dus een standaardinstallatie heeft de regel niet nodig. Andere servers hebben hun eigen tabellen; vraag het aan wie de uwe beheert.

Geblokkeerd door CORS-beleid

Modulescripts en lettertypen die van een ander adres worden geladen, hebben een Access-Control-Allow-Origin-header van dat adres nodig. In onze test kon een pagina op de ene poort geen modulescript van een andere poort laden totdat de tweede server de header stuurde. In de praktijk is de oplossing saai: houd de bestanden van de game bij elkaar in één map op één adres, zo zijn de pakketten gebouwd. U hebt geen CORS nodig om de game in een iframe op een andere site in te sluiten, omdat het iframe gewoon het adres van de game laadt. Een CORS-fout binnen een insluiting komt meestal van een sandbox-attribuut, zoals hierboven beschreven.

Gemengde content op een https-pagina

Een pagina die via https wordt geserveerd, kan geen scripts of iframes via http laden: browsers blokkeren beide, en MDN noemt ook lettertypen en fetch-verzoeken onder de geblokkeerde typen. Gebruik https:// in de src van het iframe en in elk volledig adres dat u hebt getypt. De eigen bestanden van de game gebruiken relatieve paden, dus ze volgen het schema van het adres dat u opende. Opent het https-adres helemaal niet, schakel dan eerst het certificaat in het paneel van uw host in.

Het iframe zegt "refused to connect"

In onze test logde Chromium deze regel, met het adres van het geblokkeerde frame tussen de eerste aanhalingstekens: Refused to display 'https://game-host.example/' in a frame because it set 'X-Frame-Options' to 'sameorigin'. De server die de game host, stuurde die header. SAMEORIGIN staat insluiting alleen toe vanaf hetzelfde adres en DENY staat het nooit toe; een frame-ancestors-regel in een Content-Security-Policy-header doet iets vergelijkbaars. Wijzig de header voor de map van de game, of serveer de pagina en de game vanaf één adres.

Eerst geen geluid

Browsers blokkeren audio tot de eerste tik of klik, en daarom opent Gridspark met een tik-om-te-starten-scherm. Tik één keer en controleer dan het volume en de rechten van de browser.

Bekijk Puttide, de golfeditie met een hostklare build

De game bijwerken zonder een half oude versie te serveren

Browsers cachen scripts, dus na een upload kunt u of een speler nog naar de oude game kijken. De handleiding van Gridspark geeft de regel: maak een back-up van uw wijzigingen, vervang de speelbare bestanden als één set, test, en ververs geforceerd als de host oude modules cachet. Meng geen oude en nieuwe modules. Een game die uit veel kleine bestanden bestaat die elkaar importeren, is het verkeerde om half bij te werken.

Edities met een service worker houden een eigen cache bij. Zabum is een PWA: ververs na een update geforceerd (Ctrl of Cmd plus Shift plus R). Hebt u audiobestanden vervangen, wijzig dan de cachenaam in sw.js (het voorbeeld in de handleiding gaat van zabum-v5 naar zabum-v6) en upload dat bestand. Staat uw site achter een CDN, leeg dan ook zijn cache. Van de handleidingen die we lazen, is Zabum de enige PWA; de handleidingen van Velvet Pool en Puttide zeggen met zoveel woorden dat de hunne geen installeerbare offline app is.

Lees de changelog voordat u bestanden vervangt en bewaar een kopie van alles wat u hebt bewerkt. Opgeslagen voortgang staat in de browser van elke speler, niet in de map die u uploadt, dus het vervangen van de bestanden wist die niet.

Bekijk Zabum, de PWA-editie met een optioneel PHP-klassement

Waar voortgang wordt bewaard, en wat het wissen van de browser doet

Deze edities hebben geen accounts en geen serverdatabase. Instellingen, taal, de huidige ronde en persoonlijke records staan in de local storage van de browser, en er wordt niets naar Polar Games gestuurd. De handleiding van Gridspark noemt de sleutels gridspark.standalone.v1.*; na één zet zagen we gridspark.standalone.v1.best en gridspark.standalone.v1.save.

Opslag hoort bij het adres (protocol, host en poort), niet bij de map. We controleerden het op drie manieren. Een kopie van Gridspark in een andere map van hetzelfde adres las dezelfde opgeslagen waarden. Dezelfde game, geopend als localhost in plaats van 127.0.0.1, begon leeg, en hetzelfde adres op een andere poort ook. De handleiding van Zabum voegt toe dat http en https, www en niet-www, en subdomeinen elk hun eigen opslag hebben.

• Het wissen van sitegegevens of cookies wist de opgeslagen game en de records. In een privévenster blijft voortgang mogelijk alleen voor de sessie bestaan; de game blijft draaien wanneer opslag is geblokkeerd.
• Een andere browser of een ander apparaat begint op nul. Er is geen synchronisatie en geen account om op in te loggen.
• Het adres wijzigen zet iedereen terug: http naar https, www naar niet-www, een nieuw domein.
• De game naar een andere map van hetzelfde adres verplaatsen behoudt de opgeslagen voortgang, zoals onze Gridspark-test liet zien.

Een testchecklist voordat u de link deelt

1. Open het definitieve adres in de browsers die uw spelers gebruiken: een Chromium-browser (Chrome of Edge), Firefox en Safari. Onze eigen tests liepen alleen in Chromium, dus deze lijst is voor u om af te werken.
2. Open hem op een echte telefoon, eerst op het eigen adres van de game en dan in uw pagina, in beide standen.
3. Beperk de verbinding in de ontwikkelaarstools en kijk naar de eerste lading. Gridspark, ongecomprimeerd geserveerd vanaf onze lokale server, had ongeveer 0,5 MB en 26 verzoeken nodig om het startscherm te bereiken. Met Chromium begrensd op 1,6 Mbit/s en 150 ms latentie verscheen het scherm na ongeveer 3 seconden. De hele map game/ is op onze kopie ongeveer 3,4 MB; Velvet Pool is ongeveer 7,3 MB en Puttide ongeveer 15 MB. Hebben oude telefoons het moeilijk, dan stelt de handleiding van Zabum voor te controleren of uw host bestanden comprimeert met gzip of brotli.
4. Doe een zet, herlaad en controleer of Continue en de topscore er zijn.
5. Tik één keer en controleer of het geluid start. Stilte vóór de eerste tik is normaal.
6. Open een privévenster. De game moet nog steeds draaien, ook al vergeet hij de voortgang als u sluit.
7. Lees de tabbladen Console en Network bij een eerste lading: geen rode regels, geen 404’s.
8. Controleer bij een insluiting of de knop voor volledig scherm verschijnt en of het frame op een telefoon hoog genoeg is.

Veelgestelde vragen

Heb ik PHP, een database of een speciale server nodig om een HTML5-game te hosten?

Niet voor onze edities zoals geleverd. Ze zijn statisch: upload de map game/ naar een host die bestanden serveert via HTTP of HTTPS en open hem. Zabum en Ricopop hebben een optioneel klassement dat wel PHP 7.4 of nieuwer en een beschrijfbare map vraagt.

Kan ik gewoon op index.html dubbelklikken?

Nee. Browsers blokkeren gamemodules op file://, en de pagina blijft leeg. Open de game via een http- of https-adres, op uw host of op een lokale testserver zoals python -m http.server 8765.

Heb ik HTTPS nodig?

De handleidingen zeggen HTTPS te gebruiken voor openbare hosting. De handleiding van Zabum zegt dat Toevoegen aan beginscherm het nodig heeft, en een https-pagina kan geen http-iframe insluiten omdat browsers dat als gemengde content blokkeren.

Hoe voeg ik de game toe aan een WordPress-pagina?

Upload de map met de bestandsbeheerder van uw host of via FTP, open het adres om te bevestigen dat hij speelt, en voeg dan het iframe toe in een blok Aangepaste HTML. Bij gebruikers zonder de capability unfiltered_html worden iframes verwijderd, dus controleer de rol van wie de pagina bewerkt.

Waar wordt voortgang bewaard, en wat als spelers hun browsergegevens wissen?

In de local storage van de browser, per adres. Het wissen van sitegegevens wist de voortgang, een andere browser of een ander apparaat begint leeg, en het wijzigen van het domein of wisselen tussen http en https zet haar terug. Er zijn geen accounts en er wordt niets naar ons gestuurd.

Host Polar Games de game voor mij?

Nee. De winkel verkoopt de bestanden. Support dekt vragen over het installeren en gebruiken ervan; hosting en installatie op uw server zijn aparte diensten waarvoor we vóór aanvang een offerte geven.

Volgende stap

Bent u nog bezig HTML5-games voor uw website te kiezen, dan noemt elke itempagina de vereisten, linkt naar de handleiding en laat u de demo spelen vóór u betaalt. Lees eerst het installatiehoofdstuk van de handleiding: dat is de pagina die u voor het werk uit deze gids zult gebruiken.

Bekijk de HTML5-gametemplates