Three.js integration
Native Three.js setup, integration source and export guidance.
Downloads for this guide
Three.js source packageSource + configuration/adapter + README; engine verification notes included.Download game.jsIndividual native integration source.Support and prerequisites
Verified in local desktop and mobile-viewport Chromium: this bundled starter rendered inside Play Island's real sandbox and sent an accepted start event. Complete gameplay, other renderers and physical devices still require release-specific testing. The same per-game event registration and provider approval requirements apply. Download the source package and read README.txt before building. Browser samples never need a secret key.
Set up the project
Use Node 22+, npm install, then npm run build. The source targets Three.js 0.170.0, creates a WebGLRenderer and uses Raycaster against an Icosahedron mesh. Pointer coordinates use canvas bounds so CSS scaling remains accurate. The animation loop respects reducedMotion; pagehide disposes geometry, material and renderer. The engine is bundled locally. ZIP the contents of build/ and test WebGL2 on the devices you claim to support.
Native integration example
import * as THREE from 'three';
// Three.js: raycast a mesh; pointer coordinates are relative to the canvas.
async function main() {
const status = document.querySelector('#status');
const renderer = new THREE.WebGLRenderer({antialias:true});
renderer.setSize(720,500); document.body.appendChild(renderer.domElement);
const scene = new THREE.Scene(); scene.background = new THREE.Color(0x10251d);
const camera = new THREE.PerspectiveCamera(60,720/500,0.1,100); camera.position.z=5;
const geometry = new THREE.IcosahedronGeometry(0.6), material = new THREE.MeshNormalMaterial();
const target = new THREE.Mesh(geometry,material); scene.add(target);
const raycaster = new THREE.Raycaster(), pointer = new THREE.Vector2();
let count = 0, busy = true, ended = false, startedAt = 0;
const config = await PIExample.connect();
renderer.setAnimationLoop(() => { if (!config.reducedMotion) target.rotation.y += 0.005; renderer.render(scene,camera); });
renderer.domElement.addEventListener('pointerdown',async event => {
if (busy || ended) return;
const bounds = renderer.domElement.getBoundingClientRect();
pointer.set((event.clientX-bounds.left)/bounds.width*2-1,-(event.clientY-bounds.top)/bounds.height*2+1);
raycaster.setFromCamera(pointer,camera); if (!raycaster.intersectObject(target).length) return;
busy = true;
try {
if (count < 5) { count++; await PIExample.report('progress',{progress:count*20}); target.position.x=(Math.random()-0.5)*3; status.textContent=`${count}/5. Tap again after 4 seconds to finish.`; }
else if (performance.now()-startedAt >= 4000) { await PIExample.report('completed',{score:50,progress:100}); ended=true; status.textContent='Run accepted. Reload to replay.'; }
busy=false;
} catch (error) { status.textContent=error.message+' Reload after fixing the integration.'; }
});
await PIExample.report('started',{}); startedAt=performance.now(); busy=false; status.textContent='Collect the crystal five times.';
window.addEventListener('pagehide',() => { renderer.setAnimationLoop(null); geometry.dispose(); material.dispose(); renderer.dispose(); },{once:true});
}
main().catch(error => { document.querySelector('#status').textContent=error.message; });Event lifecycle and errors
The project uses the supplied client.js helper to call the real injected PlayIsland SDK. It waits for configuration and acknowledgement callbacks. The helper serializes reports, detects rejected events and stops after a timeout or rejection. It does not manufacture accepted events offline. The example's proposed registry permits score (integer 0–1,000,000) and progress (number 0–100); both are optional in that proposal. Staff must publish the relevant definitions for your game. Other games may have different required fields. Do not copy a built-in game's specialized counters. Wait for real gameplay before reporting completion; the server rejects completed within the first three seconds of a session. Stop after terminal acceptance; use started to begin a new run or reload the launcher. On error, display the reason, correct the problem and reload to obtain a clean sequence.
Test, export and submit
- Test the engine's own rendering and controls locally. A standalone/editor launch will not connect to Play Island.
- Build using the setup instructions above and inspect the resulting runtime files.
- Follow ZIP packaging and provider submission.
- Use the visual preview for loading/layout. Use a published /play/ launch for actual accepted-event tests.
- Verify configuration, accepted start/progress/result, guest behavior, signed-in receipts if configured, replay and mobile controls.
Saves, exit, platform leaderboard navigation and general player profiles are not available automatically to your new game. See feature availability before adding those buttons.
Engine reference
Three.js WebGLRenderer explains the native engine/browser mechanism. The Play Island contract is defined by the platform implementation, not by the engine documentation.