Héberger un jeu HTML5 sur son site : envoi, iframe, dépannage

Comment héberger un jeu HTML5, en une phrase : envoyez le contenu de son dossier game/ sur n’importe quel hébergement qui sert des fichiers statiques, gardez les sous-dossiers exactement tels quels, puis ouvrez l’adresse du dossier dans un navigateur. Le dossier game/ prêt à héberger de chaque édition de notre marketplace fonctionne tel quel : ni PHP, ni base de données, ni étape de build, ni compte ; l’hébergeur n’a donc qu’à remettre des fichiers au navigateur du joueur.

C’est tout le travail quand tout se passe bien. Ce guide traite des autres jours : un écran blanc, des erreurs 404, un message de type MIME, une iframe qui refuse d’afficher quoi que ce soit. Nous vendons ces modèles ; lisez donc ceci comme un manuel de terrain pour nos propres paquets. Nous avons servi des copies de Gridspark et de Velvet Pool depuis un serveur local jetable, cassé Gridspark volontairement de plusieurs façons, et lu les manuels publics d’autres éditions. Quand une affirmation vient d’un manuel et non de notre propre test, nous le disons.

Ce que l’hébergement d’un jeu HTML5 implique vraiment

Un hébergement statique stocke des fichiers et les remet aux navigateurs à la demande. Il n’exécute jamais votre jeu ; c’est le navigateur du joueur qui le fait. C’est pourquoi les prérequis de nos éditions sont si simples : un navigateur récent, un hébergement qui sert des fichiers statiques en HTTP ou HTTPS, et ni PHP, ni base de données, ni compte pour jouer. Le dossier game/ est déjà construit : le publier n’exige ni npm ni étape de build.

Deux limites à connaître avant de commencer. Certaines éditions ont des parties optionnelles qui ne sont pas statiques : Zabum et Ricopop indiquent un classement optionnel qui demande PHP 7.4 ou plus récent et un dossier accessible en écriture, et les éditions TypeScript (Beep Out, Pinloop, Trimora, Twirldrop, Riffvolt, Sunset Rally, Tenguin, Mochi Monsters, Deepforge, Barricade Z et Zabum) n’ont besoin de Node.js que si vous voulez modifier la source et reconstruire ; chaque manuel donne la version. Velvet Pool, Puttide, Ricopop et Gridspark sont livrés en JavaScript simple, sans étape de compilation entre vos modifications et les fichiers que vous envoyez. Rien de tout cela n’est nécessaire pour publier le jeu tel que livré. Et l’hébergement lui-même ne fait pas partie de l’achat. Les conditions de la boutique rangent l’hébergement et l’installation sur votre serveur parmi les services distincts que nous chiffrons avant tout travail ; le support couvre les questions sur l’installation et l’utilisation des fichiers fournis.

Ce qui part en ligne, et ce qui reste sur votre ordinateur :

• Envoyez tout le contenu de game/ : index.html, scripts, styles, images, sons et polices.
• Laissez de côté source/ (la copie modifiable pour développeurs), documentation/ (le manuel) et le ZIP lui-même. Le manuel de Zabum cite l’envoi de source/ par erreur parmi les causes d’erreurs 404 comme main.tsx.
• Conservez, à côté de votre produit, les mentions de licences tierces fournies avec le paquet, comme le demandent les conditions.

Voir Gridspark, l’édition que nous utilisons comme exemple

Héberger un jeu HTML5 : le chemin court du ZIP à la page jouable

Ces étapes suivent les chapitres d’installation des manuels de Velvet Pool, Puttide, Gridspark et Sunset Rally, plus les vérifications que nous avons ajoutées après nos tests. Gridspark sert d’exemple, car c’est l’édition que nous avons le plus servie et le plus cassée.

1. Décompressez le paquet sur votre ordinateur. Vous y trouverez game/ (le dossier que vous publiez), source/ (la copie modifiable) et documentation/ (le manuel).
2. Facultatif mais peu coûteux : testez en local. Ouvrez un terminal dans game/, lancez python -m http.server 8765 et visitez http://localhost:8765/. Si le jeu fonctionne là, les fichiers sont bons et tout problème ultérieur vient de l’hébergement.
3. Choisissez dès maintenant l’adresse définitive, par exemple https://votre-site.example/games/gridspark/. Un sous-dossier convient, car les chemins à l’intérieur du jeu sont relatifs ; le manuel de Gridspark suggère public_html/games/gridspark/.
4. Envoyez le contenu de game/ dans ce dossier avec le gestionnaire de fichiers de votre hébergeur ou un client FTP, en gardant tous les sous-dossiers. index.html doit se retrouver directement dans le dossier, pas un niveau plus bas.
5. Ouvrez l’adresse du dossier en https, avec la barre oblique finale. Dans Gridspark, vous touchez l’écran d’accueil (les navigateurs attendent un toucher ou un clic avant d’autoriser le son) et vous appuyez sur Jouer.
6. Faites un coup, rechargez la page et vérifiez que le menu propose maintenant Continuer. Cela prouve que le navigateur enregistre la progression pour votre adresse.
7. Faites un lien vers le dossier depuis votre site, ou intégrez-le dans une page (voir la section sur l’iframe plus bas).

Un dossier Gridspark terminé contient index.html, style.css, gridspark.config.js, src/ et assets/ côte à côte, et le manuel demande de les garder ensemble. D’autres éditions s’organisent autrement (Velvet Pool a css/ et assets/ au lieu d’une seule feuille de style), mais la règle est la même : envoyez le dossier tel qu’il vient.

Pourquoi un double-clic sur index.html donne une page blanche

Les éditions que nous avons ouvertes chargent leur code sous forme de modules ES, et les navigateurs refusent de charger des modules depuis des adresses file://. Nous avons ouvert Gridspark directement depuis le disque dans Chromium et obtenu un écran sombre et vide. La console indiquait que le script était bloqué par la politique CORS, avec la raison « Cross origin requests are only supported for protocol schemes » comme http et https. Le même dossier servi par un serveur web local affichait aussitôt l’écran d’accueil. Les manuels de Velvet Pool, Puttide, Sunset Rally et Gridspark disent tous la même chose : n’ouvrez pas le jeu depuis file://.

• Ne fonctionne pas : file:///C:/Users/vous/games/gridspark/index.html
• Fonctionne : http://localhost:8765/ depuis un serveur de test local, ou https://votre-site.example/games/gridspark/ sur votre hébergement.

Nous n’avons testé que Chromium. Les manuels décrivent ce blocage comme un comportement courant des navigateurs ; prévoyez-le donc partout.

Intégrer le jeu dans une page avec une iframe

Pour afficher le jeu dans une page existante, pointez une iframe vers le dossier envoyé. Voici la balise que nous avons testée :

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

• src : l’adresse complète du dossier, avec https et la barre oblique finale.
• title : un nom court. Les lecteurs d’écran s’en servent pour décrire le cadre.
• allow="fullscreen; autoplay" : les manuels disent d’autoriser le plein écran et la lecture automatique dans une iframe quand c’est nécessaire. Dans notre test, un cadre venant d’une autre adresse sans cet attribut avait le plein écran désactivé, et Gridspark masquait simplement son bouton plein écran. L’ancien attribut allowfullscreen a donné le même résultat que allow. Un cadre ayant la même adresse que la page obtient le plein écran dans les deux cas.
• Pas d’attribut sandbox. Avec sandbox="allow-scripts" seul, Gridspark ne démarrait jamais : le cadre reçoit une origine nulle, le navigateur bloquait le script du jeu et le stockage local levait une erreur de sécurité. Ajouter allow-same-origin le fait fonctionner, mais MDN avertit que cette paire sur un cadre de même origine supprime la protection ; pour un jeu que vous hébergez vous-même, laissez donc sandbox de côté.

Le dimensionner pour les téléphones

Une boîte fixe en 16:9 est correcte sur un ordinateur et mauvaise sur un téléphone. À 390 px de large, une iframe avec aspect-ratio 16/9 ne fait que 219 px de haut, et le menu de Gridspark était coupé sous le bouton Défi du jour. Donner au cadre une hauteur de 75svh, soit les trois quarts de la hauteur de l’écran, affichait tout le menu. Votre propre page a aussi besoin d’une balise meta viewport ; les six paquets que nous avons ouverts en ont tous une dans leur propre index.html, ce qui explique que le jeu s’adapte quand on l’ouvre directement.

Le jeu fonctionne à sa propre adresse sans page autour ; un simple lien vers cette adresse est donc toujours une solution de repli valable.

Voir Velvet Pool, une édition 3D qui s’intègre de la même façon

WordPress et autres créateurs de sites

Héberger le dossier et l’afficher dans une page sont deux tâches distinctes, et dans WordPress elles font appel à deux outils différents. Tout ce qui suit vient de la documentation et de la référence développeur de WordPress, pas d’une utilisation de WordPress par nos soins.

1. Envoyez le dossier avec le gestionnaire de fichiers de votre hébergeur ou en FTP, dans l’arborescence du site (par exemple un dossier games/ à côté des dossiers de WordPress). Pas par la Médiathèque : le code de WordPress retire .html et .js des types de fichiers autorisés, sauf si l’utilisateur a la capacité unfiltered_html.
2. Ouvrez l’adresse du dossier seule avant de toucher à une page. Les règles Apache par défaut que documente WordPress n’envoient une requête vers index.php que si aucun fichier ni dossier correspondant n’existe (c’est ce que testent les conditions !-f et !-d) ; un dossier envoyé est donc servi tel quel.
3. Ajoutez l’iframe dans un bloc HTML personnalisé. WordPress documente que, pour les utilisateurs sans la capacité unfiltered_html, un Contributeur par exemple, les balises iframe sont supprimées à l’enregistrement de l’article. Si le cadre disparaît après l’enregistrement, regardez qui a modifié la page.

Autres créateurs de sites et CMS : nous ne les avons pas testés et n’affirmons rien à leur sujet. Le jeu a besoin de la même chose partout : un endroit pour le dossier envoyé et un élément d’intégration qui accepte une iframe. Si un créateur ne propose ni l’un ni l’autre, hébergez le dossier n’importe où où l’on sert des fichiers statiques et faites un lien vers son adresse.

Quand il ne démarre pas : une liste de dépannage

Ouvrez les outils de développement du navigateur (F12 dans la plupart des navigateurs de bureau) et regardez les onglets Console et Réseau avant de changer quoi que ce soit. Chacune des pannes ci-dessous laisse une ligne rouge à cet endroit, et le nom de fichier qui s’y trouve indique en général la cause.

Un écran blanc

Vérifiez dans cet ordre : l’adresse commence par http:// ou https:// ; la console n’a aucune ligne rouge ; les noms de fichiers respectent exactement les majuscules et minuscules ; et, pour les éditions 3D, WebGL2 est disponible (le manuel de Velvet Pool dit d’activer l’accélération matérielle). Les hébergements Linux traitent Game.js et game.js comme deux fichiers, ce que Windows ne fait pas : un dossier qui fonctionnait sur votre PC peut donc casser après l’envoi. Les manuels de Velvet Pool et de Zabum mettent tous deux en garde contre la casse.

404 pour src/main.js, les polices ou les images

Une partie du dossier n’est pas arrivée, ou elle est arrivée un niveau trop bas. Nous l’avons reproduit en n’envoyant que index.html, style.css et le fichier de configuration : l’écran restait blanc et l’onglet Réseau listait un 404 pour src/main.js et pour chaque police. Envoyez les dossiers manquants, ou remontez le contenu pour que index.html se trouve à l’adresse que vous ouvrez. Si des images ou des sons manquent ou sont corrompus, le manuel de Zabum suggère le FTP en mode binaire ou automatique, ou l’envoi d’un ZIP à extraire dans le gestionnaire de fichiers de l’hébergeur. Un 404, c’est un fichier manquant. Ce n’est pas un problème de MIME.

La page se charge sans style, avec d’énormes icônes

Si une réécriture ou un réglage d’URL propres sert le dossier sans la barre oblique finale, les chemins relatifs se résolvent un niveau plus haut. Nous l’avons reproduit avec un serveur de test qui renvoie la page du dossier sans redirection. Le navigateur demandait /games/style.css et /games/src/main.js au lieu des fichiers situés dans /games/gridspark/, obtenait des 404 et dessinait le menu sous forme de boutons bruts et d’icônes démesurées. Faites le lien vers le dossier avec la barre oblique finale, ou pointez directement vers index.html.

Une erreur de type MIME sur un script de module

Dans notre test, la console affichait : Failed to load module script: Expected a JavaScript-or-Wasm module script but the server responded with a MIME type of "text/plain". Les navigateurs sont stricts sur les scripts de module. Les manuels disent que le serveur doit envoyer les fichiers .js avec un type MIME JavaScript, et .wasm en application/wasm ; le manuel de Sunset Rally ajoute .mjs. L’onglet Réseau montre le Content-Type de chaque fichier. Dans les builds que nous avons ouverts, les modules sont des fichiers .js. Si vous ajoutez vos propres fichiers .mjs et qu’une ancienne configuration d’Apache ne les connaît pas, une ligne dans .htaccess règle le problème, la même que celle de notre propre site :

AddType text/javascript .mjs

La table des types d’Apache 2.4.62 sur notre machine de test associe déjà js et mjs à text/javascript et wasm à application/wasm : une installation standard n’a donc pas besoin de cette ligne. Les autres serveurs ont leurs propres tables ; demandez à la personne qui gère le vôtre.

Bloqué par la politique CORS

Les scripts de module et les polices chargés depuis une autre adresse ont besoin d’un en-tête Access-Control-Allow-Origin envoyé par cette adresse. Dans notre test, une page sur un port ne pouvait pas charger un script de module depuis un autre port tant que le second serveur n’envoyait pas l’en-tête. En pratique, le remède est banal : gardez les fichiers du jeu réunis dans un seul dossier à une seule adresse, ce qui est la façon dont les paquets sont construits. Vous n’avez pas besoin de CORS pour intégrer le jeu dans une iframe sur un autre site, car l’iframe charge simplement l’adresse du jeu. Une erreur CORS dans une intégration vient en général d’un attribut sandbox, décrit plus haut.

Contenu mixte sur une page https

Une page servie en https ne peut charger ni scripts ni iframes en http : les navigateurs bloquent les deux, et MDN cite aussi les polices et les requêtes fetch parmi les types bloqués. Utilisez https:// dans le src de l’iframe et dans toute adresse complète que vous avez saisie. Les fichiers du jeu utilisent des chemins relatifs, ils suivent donc le schéma de l’adresse que vous avez ouverte. Si l’adresse https ne s’ouvre pas du tout, activez d’abord le certificat dans le panneau de votre hébergeur.

L’iframe affiche « refused to connect »

Dans notre test, Chromium consignait cette ligne, avec l’adresse du cadre bloqué entre les premiers guillemets : Refused to display 'https://game-host.example/' in a frame because it set 'X-Frame-Options' to 'sameorigin'. Le serveur qui héberge le jeu envoyait cet en-tête. SAMEORIGIN n’autorise l’intégration que depuis la même adresse, et DENY ne l’autorise jamais ; une règle frame-ancestors dans un en-tête Content-Security-Policy joue un rôle similaire. Modifiez l’en-tête pour le dossier du jeu, ou servez la page et le jeu depuis une même adresse.

Pas de son au début

Les navigateurs bloquent le son jusqu’au premier toucher ou clic, ce qui explique que Gridspark s’ouvre sur un écran « touchez pour commencer ». Touchez une fois, puis vérifiez le volume et les autorisations du navigateur.

Voir Puttide, l’édition de golf avec une version prête à héberger

Mettre le jeu à jour sans servir une version à moitié ancienne

Les navigateurs mettent les scripts en cache : après un envoi, vous ou un joueur pouvez donc encore voir l’ancien jeu. Le manuel de Gridspark donne la règle : sauvegardez vos modifications, remplacez les fichiers jouables en un seul ensemble, testez, et faites une actualisation en profondeur si l’hébergement met d’anciens modules en cache. Ne mélangez pas anciens et nouveaux modules. Un jeu composé de nombreux petits fichiers qui s’importent les uns les autres se met mal à jour à moitié.

Les éditions dotées d’un service worker gardent leur propre cache. Zabum est une PWA : après une mise à jour, faites une actualisation en profondeur (Ctrl ou Cmd plus Maj plus R). Si vous avez remplacé des fichiers audio, changez le nom du cache dans sw.js (l’exemple du manuel passe de zabum-v5 à zabum-v6) et envoyez ce fichier. Si votre site est derrière un CDN, videz aussi son cache. Parmi les manuels que nous avons lus, Zabum est la seule PWA ; les manuels de Velvet Pool et de Puttide disent explicitement que la leur n’est pas une application hors ligne installable.

Lisez le journal des versions avant de remplacer des fichiers, et gardez une copie de tout ce que vous avez modifié. Les sauvegardes sont dans le navigateur de chaque joueur, pas dans le dossier que vous envoyez : remplacer les fichiers ne les supprime donc pas.

Voir Zabum, l’édition PWA avec un classement PHP optionnel

Où la progression est enregistrée, et ce qu’il se passe quand on vide le navigateur

Ces éditions n’ont ni comptes ni base de données serveur. Les réglages, la langue, la partie en cours et les records personnels se trouvent dans le stockage local du navigateur, et rien n’est envoyé à Polar Games. Le manuel de Gridspark nomme les clés gridspark.standalone.v1.* ; après un coup, nous avons vu gridspark.standalone.v1.best et gridspark.standalone.v1.save.

Le stockage appartient à l’adresse (protocole, hôte et port), pas au dossier. Nous l’avons vérifié de trois façons. Une copie de Gridspark dans un autre dossier de la même adresse lisait les mêmes valeurs enregistrées. Le même jeu ouvert en localhost au lieu de 127.0.0.1 démarrait à vide, tout comme la même adresse sur un autre port. Le manuel de Zabum ajoute que http et https, www et sans www, et les sous-domaines ont chacun leur propre stockage.

• Vider les données du site ou les cookies efface la partie enregistrée et les records. Dans une fenêtre privée, la progression peut ne durer que le temps de la session ; le jeu continue de fonctionner quand le stockage est bloqué.
• Un autre navigateur ou un autre appareil repart de zéro. Il n’y a ni synchronisation ni compte où se connecter.
• Changer l’adresse réinitialise tout le monde : de http à https, de www à sans www, un nouveau domaine.
• Déplacer le jeu vers un autre dossier de la même adresse conserve les sauvegardes, comme notre test avec Gridspark l’a montré.

Une liste de tests avant de partager le lien

1. Ouvrez l’adresse définitive dans les navigateurs de vos joueurs : un navigateur basé sur Chromium (Chrome ou Edge), Firefox et Safari. Nos propres tests n’ont tourné que sous Chromium ; cette liste est donc à dérouler par vous.
2. Ouvrez-la sur un vrai téléphone, d’abord à l’adresse propre du jeu puis dans votre page, dans les deux orientations.
3. Limitez la connexion dans les outils de développement et observez le premier chargement. Gridspark, servi sans compression depuis notre serveur local, a eu besoin d’environ 0,5 Mo et de 26 requêtes pour atteindre son écran d’accueil. Avec Chromium limité à 1,6 Mbit/s et 150 ms de latence, l’écran est apparu après environ 3 secondes. Le dossier game/ entier fait environ 3,4 Mo sur notre copie ; Velvet Pool pèse environ 7,3 Mo et Puttide environ 15 Mo. Si de vieux téléphones peinent, le manuel de Zabum suggère de vérifier que votre hébergeur compresse les fichiers en gzip ou en brotli.
4. Faites un coup, rechargez, et confirmez que Continuer et le meilleur score sont là.
5. Touchez une fois et vérifiez que le son démarre. Le silence avant le premier toucher est normal.
6. Ouvrez une fenêtre privée. Le jeu doit toujours fonctionner, même s’il oublie la progression à la fermeture.
7. Lisez les onglets Console et Réseau lors d’un premier chargement : pas de lignes rouges, pas de 404.
8. Dans une intégration, vérifiez que le bouton plein écran apparaît et que le cadre est assez haut sur un téléphone.

FAQ

Ai-je besoin de PHP, d’une base de données ou d’un serveur spécial pour héberger un jeu HTML5 ?

Pas pour nos éditions telles que livrées. Elles sont statiques : envoyez le dossier game/ sur un hébergement qui sert des fichiers en HTTP ou HTTPS et ouvrez-le. Zabum et Ricopop ont un classement optionnel qui, lui, demande PHP 7.4 ou plus récent et un dossier accessible en écriture.

Puis-je simplement double-cliquer sur index.html ?

Non. Les navigateurs bloquent les modules de jeu sur file://, et la page reste blanche. Ouvrez le jeu par une adresse http ou https, celle de votre hébergement ou celle d’un serveur de test local comme python -m http.server 8765.

Ai-je besoin de HTTPS ?

Les manuels disent d’utiliser HTTPS pour un hébergement public. Le manuel de Zabum précise que « Ajouter à l’écran d’accueil » l’exige, et une page https ne peut pas intégrer une iframe http, car les navigateurs la bloquent comme contenu mixte.

Comment ajouter le jeu à une page WordPress ?

Envoyez le dossier avec le gestionnaire de fichiers de votre hébergeur ou en FTP, ouvrez son adresse pour confirmer qu’il se joue, puis ajoutez l’iframe dans un bloc HTML personnalisé. Les utilisateurs sans la capacité unfiltered_html voient leurs iframes supprimées : vérifiez donc le rôle de la personne qui modifie la page.

Où la progression est-elle enregistrée, et que se passe-t-il si les joueurs vident les données de leur navigateur ?

Dans le stockage local du navigateur, par adresse. Vider les données du site l’efface, un autre navigateur ou appareil repart à vide, et changer de domaine ou passer de http à https la réinitialise. Il n’y a pas de comptes et rien ne nous est envoyé.

Polar Games héberge-t-il le jeu pour moi ?

Non. La boutique vend les fichiers. Le support couvre les questions sur leur installation et leur utilisation ; l’hébergement et l’installation sur votre serveur sont des services distincts que nous chiffrons avant tout travail.

Étape suivante

Si vous cherchez encore des jeux HTML5 pour votre site, chaque page d’article liste ses prérequis, renvoie à son manuel et vous laisse jouer à la démo avant de payer. Lisez d’abord le chapitre d’installation du manuel : c’est la page dont vous vous servirez pour le travail décrit dans ce guide.

Parcourir les modèles de jeux HTML5