unity-webgl/src/types/unity-arguments.ts

Unity-WebGL provides an easy solution for embedding Unity WebGL builds in your web projects, with two-way communication between your webApp and Unity application with advanced API's.

/**
 * WebGLContextAttributes object that contains the actual context parameters.
 * @see https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/getContextAttributes
 */
type WebGLContextAttributes = {
	/**
	 * If set to true, the context will have an alpha (transparency) channel.
	 * @default true
	 */
	readonly alpha?: boolean

	/**
	 * If set to true, the context will attempt to perform antialiased rendering
	 * if possible.
	 * @default true
	 */
	readonly antialias?: boolean

	/**
	 * If set to true, the context will have a 16 bit depth buffer. Defaults to
	 * true. Use gl.enable(DEPTH_TEST) to enable the depth test and
	 * gl.depthFunc(), gl.depthMask(), and gl.depthRange() to configure the depth
	 * test.
	 * @default true
	 */
	readonly depth?: boolean

	/**
	 * If the value is true, context creation will fail if the implementation
	 * determines that the performance of the created WebGL context would be
	 * dramatically lower than that of a native application making equivalent
	 * OpenGL calls. This could happen for a number of reasons, including an
	 * implementation might switch to a software rasterizer if the user's GPU
	 * driver is known to be unstable. And an implementation might require reading
	 * back the framebuffer from GPU memory to system memory before compositing it
	 * with the rest of the page, significantly reducing performance.
	 * @default false
	 */
	readonly failIfMajorPerformanceCaveat?: boolean

	/**
	 * Provides a hint to the user agent indicating what configuration of GPU is
	 * suitable for this WebGL context. This may influence which GPU is used in a
	 * system with multiple GPUs. For example, a dual-GPU system might have one
	 * GPU that consumes less power at the expense of rendering performance.
	 * Note that this property is only a hint and a WebGL implementation may
	 * choose to ignore it. WebGL implementations use context lost and restored
	 * events to regulate power and memory consumption, regardless of the value of
	 * this attribute.
	 * @default "default"
	 */
	readonly powerPreference?: 'default' | 'high-performance' | 'low-power'

	/**
	 * If set to true, the color channels in the framebuffer will be stored
	 * premultipled by the alpha channel to improve performance.
	 * @default true
	 */
	readonly premultipliedAlpha?: boolean

	/**
	 * If set to false, the buffer will be cleared after rendering. If you wish to
	 * use canvas.toDataURL(), you will either need to draw to the canvas
	 * immediately before calling toDataURL(), or set preserveDrawingBuffer to
	 * true to keep the buffer available after the browser has displayed the
	 * buffer (at the cost of increased memory use).
	 * @default false
	 */
	readonly preserveDrawingBuffer?: boolean

	/**
	 * Stenciling enables and disables drawing on a per-pixel basis. It is
	 * typically used in multipass rendering to achieve special effects.
	 * @default false
	 */
	readonly stencil?: boolean

	/**
	 * If set to true, the context will have an 8 bit stencil buffer. Defaults to
	 * false. Use gl.enable(STENCIL_TEST) to enable depth test and
	 * gl.stencilFunc(), gl.stencilFuncSeparate(), gl.stencilMask(),
	 * gl.stencilMaskSeparate(), gl.stencilOp(), and gl.stencilOpSeparate()
	 * to configure the stencil test.
	 * @default false
	 */
	readonly desynchronized?: boolean

	/**
	 * xrCompatible is a boolean that indicates whether the context is compatible.
	 * @default false
	 */
	readonly xrCompatible?: boolean
}

/**
 * The cache control mode determines how the Unity should cache the resource.
 * - `must-revalidate`: The cache returns to an enabled state and the file is
 *   revalidated before being loaded from the cache.
 * - `immutable`: the cache is enabled and the file is loaded from the cache
 *   without revalidation.
 * - `no-store`: The cache is disabled.
 */
type UnityCacheControlMode =
	/**
	 * The cache returns to an enabled state and the file is revalidated before
	 * being loaded from the cache.
	 */
	| 'must-revalidate'
	/**
	 * the cache is enabled and the file is loaded from the cache without revalidation.
	 */
	| 'immutable'
	/**
	 * The cache is disabled.
	 */
	| 'no-store'
	/**
	 * Fallback for when the cache control mode is not recognized.
	 */
	| string

/**
 * Banners can be used to display non-critical warnings and error messages from
 * the Unity Instance.
 */
type UnityInstanceBannerType = 'error' | 'warning'

/**
 * The Unity Arguments can be passed to a create Unity instance method in order to initialize it.
 */
export interface UnityArguments {
	/**
	 * The url to the build data file generated by Unity.
	 * @public
	 * @type {string}
	 */
	readonly dataUrl: string

	/**
	 * The url to the framework file generated by Unity.
	 * @public
	 * @type {string}
	 */
	readonly frameworkUrl: string

	/**
	 * The url to the unity code file generated by Unity.
	 * @public
	 * @type {string}
	 */
	readonly codeUrl: string

	/**
	 * The url to the web worker file generated by Unity.
	 * @public
	 * @type {string}
	 */
	readonly workerUrl?: string

	/**
	 * The url where the streaming assets can be found.
	 * @public
	 * @type {string}
	 */
	readonly streamingAssetsUrl?: string

	/**
	 * The url to the framework file generated by Unity.
	 * This is set to the memory file when memory is stored in an external file,
	 * otherwise it is set to an empty string.
	 * @public
	 * @type {string}
	 */
	readonly memoryUrl?: string

	/**
	 * The url to the unity code file generated by Unity.
	 * This is set to the JSON file containing debug symbols when the
	 * current build is using debug symbols, otherwise it is set to an empty string.
	 * @public
	 * @type {string}
	 */
	readonly symbolsUrl?: string

	/**
	 * The application's company name. This argument is treated as meta data
	 * which will be provided to the Unity Instance.
	 * @public
	 * @type {string}
	 */
	readonly companyName?: string

	/**
	 * The application's product name. This argument is treated as meta data
	 * which will be provided to the Unity Instance.
	 * @public
	 * @type {string}
	 */
	readonly productName?: string

	/**
	 * The application's product version. This argument is treated as meta data
	 * which will be provided to the Unity Instance.
	 * @public
	 * @type {string}
	 */
	readonly productVersion?: string

	/**
	 * The Canvas can appear too blurry on retina screens. The devicePixelRatio
	 * determines how much extra pixel density should be added to allow for a
	 * sharper image.
	 * @public
	 * @type {string}
	 * @see https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio
	 */
	readonly devicePixelRatio?: number

	/**
	 * If set to true, all file writes inside the Unity Application
	 * persistentDataPath directory automatically persist so that the contents are
	 * remembered when the user revisits the website the next time. If unset (or
	 * set to false), you must manually sync file modifications inside the
	 * Application persistentDataPath directory by calling the
	 * JS_FileSystem_Sync() JavaScript function.
	 */
	readonly autoSyncPersistentDataPath?: boolean

	/**
	 * When disabling the match WebGL to canvas size flag, the canvas allows for
	 * client side customization of the WebGL canvas target size instead of
	 * requiring it to always match 1:1 with the High DPI CSS size of the canvas.
	 * Supported since Unity 2021.1b
	 * @public
	 * @type {boolean}
	 * @see https://issuetracker.unity3d.com/issues/webgl-builds-dont-allow-separate-control-on-canvas-render-buffer-size
	 */
	readonly matchWebGLToCanvasSize?: boolean

	/**
	 * This object allow you to configure WebGLRenderingContext creation options
	 * which will be pass additional context attributes to the Unity canvas.
	 * @see https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext
	 */
	readonly webglContextAttributes?: WebGLContextAttributes

	/**
	 * An array of strings containing the names of the events that should be
	 * disabled on the canvas. This can be useful when you want to allow the user
	 * to interact with the canvas, but not with the Unity WebGL canvas. The
	 * default disabled events are `contextmenu` and `dragstart`.
	 */
	readonly disabledCanvasEvents?: (keyof GlobalEventHandlersEventMap)[]

	/**
	 * By default, the WebGL Cache stores the asset data file .data and
	 * AssetBundle files .bundle, and revalidates them before loading them from
	 * the cache. You can change this behavior by overriding the default
	 * caching behavior. This argument is treated as meta data which will be
	 * provided to the Unity Instance.
	 */
	readonly cacheControl?: (url: string) => UnityCacheControlMode

	/**
	 * Add an event listener using this function to receive non-critical warnings
	 * and error messages from the Unity Instance.
	 */
	readonly showBanner?: (message: string, type?: UnityInstanceBannerType) => void

	/**
	 * When assigned this method will intercept all incomming messages from the
	 * Unity Module into the console. These messages will contain both of the
	 * internal information messages as well as the debuggers log messages.
	 */
	print?: (message: string) => void

	/**
	 * When assigned this method will intercept all incomming error logs from the
	 * Unity Module into the console. These messages will contain both of the
	 * runtime problems as well as the jslib and javascript errors thrown by the
	 * Unity Instance.
	 */
	printError?: (message: string) => void
}