Unity Setup & Configuration

Understanding the Unity WebGL project structure, build configuration, and technical specifications for WPM Typing Tutor

Overview

WPM Typing Tutor is built using Unity 2019.4.41f2 LTS and compiled to WebGL for browser-based gameplay. This page covers the Unity project structure, build settings, and WebGL configuration used in the game.

Unity Version: 2019.4.41f2 LTS

Target Platform: WebGL (browsers)

Company: DefaultCompany

Product Name: mecanografia

Unity Project Information

The game is configured with the following project settings:

Build Configuration

{
  "companyName": "DefaultCompany",
  "productName": "mecanografia",
  "productVersion": "0.1",
  "unityVersion": "2019.4.41f2",
  "developmentBuild": true
}

The project is currently set to developmentBuild: true, which enables console logging and debugging features. For production deployments, consider setting this to false.

WebGL Build Configuration

Graphics API Support

The game supports both modern and legacy WebGL implementations:

WebGL 2.0

Primary graphics API with better performance and features. Supported by:

• Chrome 56+
• Firefox 51+
• Edge 79+
• Safari 15+

WebGL 1.0

Fallback graphics API for older browsers. Provides wider compatibility but with reduced features and performance.

GraphicsAPI Configuration

{
  "graphicsAPI": ["WebGL 2.0", "WebGL 1.0"],
  "webglContextAttributes": {
    "preserveDrawingBuffer": false
  },
  "backgroundColor": "#231F20",
  "multithreading": false
}

Build Artifacts

The Unity build process generates the following files:

1. INTEGRADORA.json

   Size: ~530 bytes

   Main configuration file containing build metadata, Unity version, and loader settings. This file is loaded first by UnityLoader.js to initialize the game.

2. INTEGRADORA.data.unityweb

   Size: ~5.5 MB (compressed)

   Contains game assets including:

   • Scenes and scene data
   • Sprites and textures
   • Audio files
   • Text assets and levels
   • Resource files

   Uses Gzip or Brotli compression with Unity’s custom marker for web optimization.

3. INTEGRADORA.wasm.code.unityweb

   Size: ~14.6 MB (compressed)

   WebAssembly code module containing:

   • Compiled C# scripts
   • Unity engine runtime
   • Game logic and mechanics
   • Physics and rendering systems

   This is the largest file and benefits most from compression.

4. INTEGRADORA.wasm.framework.unityweb

   Size: ~1.1 MB (compressed)

   WebAssembly framework file providing:

   • Unity runtime framework
   • Core engine systems
   • Platform abstraction layer
   • Memory management

Total compressed size: ~21 MB

Ensure your hosting environment supports serving compressed .unityweb files with appropriate MIME types and compression headers.

UnityLoader System

The Unity WebGL loader handles game initialization, asset loading, and browser compatibility checking.

Compression Support

UnityLoader includes built-in decompression for:

Gzip Decompression

// UnityLoader automatically detects Gzip compressed files
// by checking for Unity's custom marker
compression: {
  gzip: {
    hasUnityMarker: true,
    expectedComment: "UnityWeb Compressed Content (gzip)"
  }
}

Loading Process

1. Initialize UnityLoader

   The UnityLoader.js script is loaded first, providing the core loading functionality.

   <script src="Build/UnityLoader.js"></script>
   
2. Instantiate Game

   Call UnityLoader.instantiate() with the container and config:

   UnityLoader.instantiate("unityContainer", "Build/INTEGRADORA.json", {
     onProgress: UnityProgress
   });
   
3. Download & Decompress

   UnityLoader downloads and decompresses the .unityweb files:

   • Detects compression type (Gzip/Brotli/none)
   • Downloads files asynchronously
   • Decompresses using Web Workers
   • Reports progress to callback
4. Initialize WebGL Context

   Creates the WebGL context with specified attributes:

   • Selects WebGL 2.0 or 1.0 based on browser support
   • Initializes canvas element
   • Sets up rendering context
5. Start Game

   Transfers control to the Unity runtime:

   • Loads game scenes
   • Initializes game systems
   • Begins main game loop

Browser Compatibility

System Requirements

Supported Browsers

Fully Supported:

• Chrome 56+ (recommended)
• Firefox 51+
• Edge 79+
• Safari 15+

Limited Support:

• Safari 10.1-14.x (WebGL 1.0 only)
• Older Firefox/Chrome versions (performance issues)

Not Supported

Not Supported:

• Internet Explorer (any version)
• Mobile browsers (use React Native app instead)
• Opera Mini
• Very old browser versions without WebGL

Compatibility Checking

UnityLoader includes automatic compatibility detection:

Compatibility Detection

// Checks performed by UnityLoader:
- Browser supports WebGL
- Browser supports required graphics API (WebGL 1.0 or 2.0)
- Browser supports WebAssembly
- Multithreading support (if enabled)
- Sufficient memory available

The loader displays user-friendly error messages if the browser doesn’t meet requirements, with suggestions to upgrade or switch browsers.

Development vs Production

Development Build

The current configuration uses a development build:

{
  "developmentBuild": true
}

Development builds include:

• Console logging and debug output
• Unity Profiler support
• Symbol information for debugging
• Unoptimized code for faster iteration

Production Build Recommendations

For production deployment, modify the build configuration:

1. Disable Development Build

   In Unity Build Settings, uncheck “Development Build”

   {
     "developmentBuild": false
   }
   
2. Enable Code Optimization

   Set code optimization to “Master” or “Release” in build settings for:

   • Smaller file sizes
   • Better performance
   • No debug symbols
3. Configure Compression

   Choose compression method in Unity Player Settings:

   • Brotli: Best compression (~30% better than Gzip)
   • Gzip: Good compatibility, decent compression
   • Disabled: Fastest loading but largest files
4. Strip Engine Code

   Enable code stripping to remove unused Unity features:

   • Reduces build size significantly
   • Removes unused engine modules
   • Keep only required functionality

Always test production builds thoroughly before deployment. Production builds may behave differently than development builds.

Error Handling

Common Build Errors

WebGL not supported

Error: Browser does not support WebGL

Solution:

• Upgrade to a modern browser
• Enable hardware acceleration
• Update graphics drivers
• Check if WebGL is disabled in browser settings

Out of memory

Error: Cannot allocate enough memory for WebGL content

Solution:

• Close other browser tabs
• Restart browser
• Reduce WebGL memory allocation in Unity Player Settings
• Use a 64-bit browser

Failed to download

Error: Failed to download .unityweb files

Solution:

• Check network connection
• Verify server is running and accessible
• Check CORS headers on server
• Verify file paths in INTEGRADORA.json

Decompression failed

Error: Failed to decompress build files

Solution:

• Verify files are not corrupted
• Check server compression settings
• Ensure Unity build completed successfully
• Try different compression method (Gzip vs Brotli)

Performance Optimization

Loading Performance

Enable Compression

Use Brotli compression for ~30% smaller files than Gzip. Configure in Unity WebGL Player Settings.

Server Configuration

Configure your web server to:

• Serve .unityweb files pre-compressed
• Set proper MIME types
• Enable HTTP/2 for parallel loading
• Use CDN for global distribution

Code Stripping

Enable “Strip Engine Code” in Player Settings to remove unused Unity engine features and reduce build size.

Asset Optimization

Optimize game assets:

• Compress textures
• Use sprite atlases
• Reduce audio quality for non-critical sounds
• Remove unused assets

Runtime Performance

Performance Tips

// Unity WebGL performance considerations:
- Use object pooling to reduce garbage collection
- Minimize draw calls with sprite atlases
- Avoid expensive operations in Update()
- Use coroutines for async operations
- Limit particle effects on lower-end devices
- Profile regularly with Unity Profiler

Next Steps

React Native Integration

Learn how the mobile app integrates Unity WebGL

Deployment Guide

Deploy the game to production hosting

React Native Setup

Configure mobile development environment

Platform Overview

Learn about web platform features