Unity WebGL

WebGL Game Template Guidelines

Best practices for Unity WebGL builds to ensure your game works on desktop and mobile. Referenced from Tournament SDK and Uploading.

Back to Docs

Common Issues

1. Hardcoded Canvas Dimensions

Problem: Fixed pixel dimensions don't adapt to different screens.

<!-- BAD -->
<canvas id="unity-canvas" width=1920 height=1080>
 
<!-- GOOD -->
<canvas id="unity-canvas" tabindex="-1"></canvas>

With CSS:

#unity-canvas {
  width: 100%;
  height: 100%;
  max-width: 100%;
  max-height: 100%;
}

2. Missing tabindex on Canvas

Problem: Without tabindex="-1", touch and keyboard input may not register properly.

<!-- BAD -->
<canvas id="unity-canvas"></canvas>
 
<!-- GOOD -->
<canvas id="unity-canvas" tabindex="-1"></canvas>

Impact: Two-tap problem on mobile (first tap focuses, second registers).

3. Missing touch-action CSS

Problem: Browser intercepts touches for scrolling/zooming instead of passing to game.

/* Required for mobile */
#unity-canvas {
  touch-action: none;
}
 
#unity-container.unity-mobile {
  position: fixed;
  top: 0; left: 0;
  width: 100%; height: 100%;
  touch-action: none;
  -webkit-touch-callout: none;
  -webkit-user-select: none;
  user-select: none;
}

4. Missing window.unityInstance

Problem: RCADIA needs access to the Unity instance for SDK communication.

// BAD - instance not exposed
createUnityInstance(canvas, config).then((instance) => {
  // instance only in scope
});
 
// GOOD - instance exposed globally
window.unityInstance = null;
 
createUnityInstance(canvas, config).then((instance) => {
  window.unityInstance = instance;
});

5. No Mobile Detection

Add mobile-specific handling:

if (/iPhone|iPad|iPod|Android/i.test(navigator.userAgent)) {
  var meta = document.createElement('meta');
  meta.name = 'viewport';
  meta.content = 'width=device-width, height=device-height, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover';
  document.head.appendChild(meta);
 
  container.className = 'unity-mobile';
 
  document.addEventListener('touchmove', function(e) {
    if (e.target === canvas) e.preventDefault();
  }, { passive: false });
}

Recommended Template

NOTEDownload the template

A standardized template that handles all mobile compatibility issues.

Download Template

Key features of the template:

Responsive canvas sizing
Mobile viewport handling
Touch event prevention
RCADIA loading animation
window.unityInstance exposed
Fullscreen support via Unity's built-in button

Unity Build Settings

NOTEFor best mobile compatibility

Use Legacy Input System — New Input System has WebGL mobile issues
Test on actual mobile devices — emulators miss issues
Design for multiple aspect ratios — don't assume 16:9
Include fullscreen button in your game UI

Recommended Player Settings

Setting	Value
Compression Format	Gzip
Exception Handling	None
Memory Size	256MB minimum

Mobile Limitations

WARNINGUnity WebGL mobile limits

Unity WebGL has known limitations on mobile. These are Unity limitations, not RCADIA issues.

Issue	Description	Workaround
Single tap not registering	iOS Safari specific	Use hold/drag or Legacy Input
Two-tap problem	Canvas needs focus	Ensure `tabindex="-1"`
New Input System	Doesn't work on WebGL mobile	Use Legacy Input System
Virtual keyboard	Doesn't appear	Use WebGLInput.mobileKeyboardSupport

Pre-Submission Checklist

Before uploading your game:

Canvas has tabindex="-1"
No hardcoded pixel dimensions
Mobile viewport meta tag added dynamically
touch-action: none on canvas for mobile
window.unityInstance exposed globally
Tested on actual mobile device
Using Legacy Input System (not New Input System)

Support

Need help with your WebGL build?

Discord: discord.gg/wbP4rmCEPs
Email: support@rcadia.xyz