visualspec.1.0 RC
GitHub
Module

Game

Visual state of a game

Game describes what the player sees: levels, characters as visual entities, HUD, spatial UI, and cutscenes. It does not describe rules, scoring code, or networking.

Use this module when You need the visual contract of a game view: the HUD, the space, and how visual state is shown.

Keep in mind. Gameplay rules stay outside the document. If a rule changes pixels, record the visual state, not the rule engine.

Raw schema:/schema/1.0/modules/game.schema.json · https://visualspec.dev/schema/1.0/modules/game.schema.json

How to read a definition.The paragraphs say what to write and why. “Exact constraints” opens the schema keywords (type, pattern, bounds) for people checking a validator. A sample at the bottom of each definition is the smallest JSON that shows the required shape. Values such as $ref inside a sample point at another definition. They are not fields you copy into a document.

spatialUI

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include mode.

You may omit anchorRef, billboard, occlusion, scaleMode, interaction, and distance. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
moderequired"world-space" | "screen-space" | "anchored" | "entity-attached"

Pick one of the 4 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "world-space"
  • "screen-space"
  • "anchored"
  • "entity-attached"
anchorRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

billboard"none" | "camera" | "axis-y"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "none"
  • "camera"
  • "axis-y"
occlusion"depth-test" | "always-visible" | "fade"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "depth-test"
  • "always-visible"
  • "fade"
scaleMode"world" | "screen" | "distance"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "world"
  • "screen"
  • "distance"
interaction"pointer" | "gaze" | "ray" | "direct" | "none"

Pick one of the 5 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "pointer"
  • "gaze"
  • "ray"
  • "direct"
  • "none"
distancenumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

spatialUIJSON
{  "mode": "world-space"}

character

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id and entityRef.

You may omit rigRef, skeletonRef, animationController, visualStateMappings, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

entityRefrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

rigRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

skeletonRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

animationControllerobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You may omit initialState, states, and transitions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
initialStateid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

statesarray<object>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id and name.

You may omit motionRef, assetRef, speed, and loop. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

namerequiredstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
motionRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

assetRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

speednumber

Write a number. Decimals are allowed.

The number must be at least 0.

Exact constraints
type
number
minimum
0
loopboolean

Write true or false.

Exact constraints
type
boolean
transitionsarray<object>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include from and to.

You may omit duration, blend, and eventRef. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
fromrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

torequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

durationduration

This is not a new shape. It reuses duration from the common module. Open that definition for the fields you can write.

blend"linear" | "crossfade" | "additive"

Pick one of the 3 listed values. Any other value is invalid. The list is closed on purpose so tools agree on the same words.

Exact constraints
Allowed values
  • "linear"
  • "crossfade"
  • "additive"
eventRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

visualStateMappingsobject
Exact constraints
type
object
additional properties
object
additionalPropertiesobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You may omit stateRef, motionRef, effectRefs, and appearance. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
stateRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

motionRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

effectRefsarray<id>

Write a list. Each item follows the shape described under items.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemsid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

appearanceappearance

This is not a new shape. It reuses appearance from the appearance module. Open that definition for the fields you can write.

extensionsextensions

This is not a new shape. It reuses extensions from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

characterJSON
{  "id": {    "$ref": "common#id"  },  "entityRef": {    "$ref": "common#id"  }}

level

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id and sceneRefs.

You may omit name, areas, environment, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

namestring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
sceneRefsrequiredarray<id>

Write a list. Each item follows the shape described under items.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemsid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

areasarray<object>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id.

You may omit sceneRef, bounds, and environment. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

sceneRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

boundsbounds

This is not a new shape. It reuses bounds from the common module. Open that definition for the fields you can write.

environmentenvironment

This is not a new shape. It reuses environment from the world module. Open that definition for the fields you can write.

environmentenvironment

This is not a new shape. It reuses environment from the world module. Open that definition for the fields you can write.

extensionsextensions

This is not a new shape. It reuses extensions from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

levelJSON
{  "id": {    "$ref": "common#id"  },  "sceneRefs": []}

game

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You may omit worldRef, levels, characters, hud, cameraRef, visualStates, cutscenes, spatialUI, and extensions. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
worldRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

levelsarray<level>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemslevel

This is not a new shape. It reuses level from the game module. Open that definition for the fields you can write.

charactersarray<character>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemscharacter

This is not a new shape. It reuses character from the game module. Open that definition for the fields you can write.

hudobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You may omit sceneRef, componentRefs, and safeArea. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
sceneRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

componentRefsarray<id>

Write a list. Each item follows the shape described under items.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemsid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

safeAreaboolean

Write true or false.

Exact constraints
type
boolean
cameraRefid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

visualStatesarray<object>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id and externalName.

You may omit stateRefs, actionRefs, and effectRefs. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

externalNamerequiredstring

Write a text value.

An empty string is not allowed.

Exact constraints
type
string
min length
1
stateRefsarray<id>

Write a list. Each item follows the shape described under items.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemsid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

actionRefsarray<id>

Write a list. Each item follows the shape described under items.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemsid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

effectRefsarray<id>

Write a list. Each item follows the shape described under items.

Each item in the list must be different. Duplicates are invalid.

Exact constraints
type
array
unique items
true
itemsid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

cutscenesarray<object>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsobject

Write an object. Only the fields named below are allowed. Unknown fields are rejected so a typo cannot hide inside the document.

You must include id and timelineRef.

You may omit skippable and restoreCamera. Leave a field out when you have nothing to say. Do not invent a placeholder.

Exact constraints
type
object
additional properties
forbidden
idrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

timelineRefrequiredid

This is not a new shape. It reuses id from the common module. Open that definition for the fields you can write.

skippableboolean

Write true or false.

Exact constraints
type
boolean
restoreCameraboolean

Write true or false.

Exact constraints
type
boolean
spatialUIarray<spatialUI>

Write a list. Each item follows the shape described under items.

Exact constraints
type
array
itemsspatialUI

This is not a new shape. It reuses spatialUI from the game module. Open that definition for the fields you can write.

extensionsextensions

This is not a new shape. It reuses extensions from the common module. Open that definition for the fields you can write.

Smallest example

Required fields only, with placeholder values. Replace them with the real intent.

gameJSON
{  "worldRef": {    "$ref": "common#id"  },  "levels": [],  "characters": [],  "hud": {    "sceneRef": {      "$ref": "common#id"    },    "componentRefs": [],    "safeArea": true  }}