DocumentationBot: Expand game integration guide with step-by-step build, content, and SDK instructions

2026-10-09T20:38:00Z

Expand game integration guide with step-by-step build, content, and SDK instructions

Show changes

DocumentationBot: Explain creating a Vertex game connection step by step

2026-10-09T18:28:20Z

Explain creating a Vertex game connection step by step

Show changes

DocumentationBot: Clarify custom content navigation and standardize asset examples

2026-10-04T16:30:18Z

Clarify custom content navigation and standardize asset examples

← Older revision		Revision as of 12:30, 4 October 2026
Line 11:		Line 11:
	# Add the Vertex package through '''Window → Package Manager → Add package from disk…''' and select its <code>package.json</code>. Keep the package folder available to the project.		# Add the Vertex package through '''Window → Package Manager → Add package from disk…''' and select its <code>package.json</code>. Keep the package folder available to the project.
	# Create a small map in Vertex without a game connection. Use plain brush geometry for the first import.		# Create a small map in Vertex without a game connection. Use plain brush geometry for the first import.
	# Choose '''File → Export compiled meshes…''' and save a <code>.vertexmesh</code> under your Unity project's <code>Assets/GameContent/Maps/~~my_arena~~/</code> folder.		# Choose '''File → Export compiled meshes…''' and save a <code>.vertexmesh</code> under your Unity project's <code>Assets/GameContent/Maps/arena_mycustommap/</code> folder.
	# Unity imports it as a prefab. Place it in a scene and assign material bindings on the imported asset where needed. Enable the placed root if it is inactive.		# Unity imports it as a prefab. Place it in a scene and assign material bindings on the imported asset where needed. Enable the placed root if it is inactive.
	# Add your game's player, camera, and startup objects, then test movement and collision.		# Add your game's player, camera, and startup objects, then test movement and collision.

DocumentationBot: Version 1

2026-10-01T04:13:05Z

Version 1

New page

{{VertexNav}}

You can use Vertex to make levels for your own game. Start by importing geometry. Add a game connection when you want your materials, entities, and build commands inside the editor.

Unity has a working integration package. Other engines can read Vertex's map format, but need their own engine adapter for compilation and playtesting. A game profile alone does not add support for another engine.

== First level in Unity ==

You need a matching Vertex build and the <code>com.vellocet.vertex</code> Unity package. The Grimwar SDK includes that package under <code>Compiler/Packages/com.vellocet.vertex/</code>; copy it to a stable location for your project so a Steam update cannot replace it. Use Unity 6.3 for this integration; each finished SDK pins the exact editor version it builds with. Grimwar's SDK pins <code>6000.3.17f1</code>.

# Add the Vertex package through '''Window → Package Manager → Add package from disk…''' and select its <code>package.json</code>. Keep the package folder available to the project.
# Create a small map in Vertex without a game connection. Use plain brush geometry for the first import.
# Choose '''File → Export compiled meshes…''' and save a <code>.vertexmesh</code> under your Unity project's <code>Assets/GameContent/Maps/my_arena/</code> folder.
# Unity imports it as a prefab. Place it in a scene and assign material bindings on the imported asset where needed. Enable the placed root if it is inactive.
# Add your game's player, camera, and startup objects, then test movement and collision.

Keep the <code>.vertex</code> source beside the export. Re-export after editing; preserve the map and object IDs so Unity can retain references to imported objects. OBJ and FBX export are also available when you only need a model, but they omit entity and collision data.

This gives you an editable level and a repeatable import before you build an SDK for other creators.

== Define the game connection ==

Vertex separates the connection into a few files:

{| class="wikitable"
! File !! What you supply
|-
| <code>.vertexgame</code> || Game identity, units, exact engine version, catalog references, and optional build policy.
|-
| <code>.vertexassets</code> || Available materials, models, and other native assets, with previews and ownership.
|-
| Entity catalog JSON || Placeable entity types, editable properties, and script inputs and outputs.
|-
| <code>.vertexsdk</code> || Paths to the game profile and compiler, with an optional local editor connection.
|}

Use your own stable game and catalog IDs. Display names are separate. Vertex uses right-handed, Y-up coordinates; its Unity importer handles the coordinate conversion. Set <code>defaultMetersPerUnit</code> to your preferred authoring scale. A value of <code>1</code> means one map unit per metre; <code>0.0254</code> means inches.

A minimal profile with no catalogs or build commands is:

<syntaxhighlight lang="json">
{
"formatVersion": 1,
"id": "com.example.mygame",
"name": "My Game",
"version": "1",
"engineId": "unity",
"engineVersion": "6000.3.17f1",
"coordinates": "right-handed-y-up",
"defaultMetersPerUnit": 1,
"entityCatalogs": [],
"assetCatalogs": []
}
</syntaxhighlight>

Use the exact version of your Unity editor in <code>engineVersion</code>. For a local connection, this layout keeps paths relative:

<syntaxhighlight lang="text">
MyGame/
MyGame.local.vertexsdk
Authoring/MyGame.vertexgame
UnityProject/Assets/
UnityProject/Packages/
UnityProject/ProjectSettings/
</syntaxhighlight>

<code>MyGame.local.vertexsdk</code>:

<syntaxhighlight lang="json">
{
"formatVersion": 1,
"game": {
"id": "com.example.mygame",
"version": "1",
"path": "Authoring/MyGame.vertexgame"
},
"compilerProject": "UnityProject",
"editorProject": "UnityProject"
}
</syntaxhighlight>

Open this connection with '''File → Open game SDK…'''. This identifies the game and local project. Build and save actions still need the implementations described below. Keep local connections out of a public SDK.

== Expose materials and models ==

# In Unity, create a '''Vertex → Asset catalog profile''' asset.
# Set a stable catalog ID and version, such as <code>mygame.base</code> and <code>1</code>.
# Add folder rules for the assets creators can use. Mark installed game assets as <code>base</code> and creator-owned assets that may ship in add-ons as <code>custom</code>.
# Export the profile with <code>VertexAssetCatalogExporter.Export</code>, or publish it together with the game profile using <code>VertexGameProfileExporter.Export</code>.
# Distribute the exported catalog and its preview folder. Reload resources in Vertex after publishing an update.

For example, an editor script can publish an existing profile asset:

<syntaxhighlight lang="csharp">
using UnityEditor;
using Vertex.Unity.Editor;

var assets = AssetDatabase.LoadAssetAtPath<VertexAssetCatalogProfile>(
"Assets/Editor/VertexAssets.asset");
VertexAssetCatalogExporter.Export(assets, catalogOutputPath);
</syntaxhighlight>

This is code for your exporter; <code>catalogOutputPath</code> is its destination outside <code>Assets</code>. Add the exported catalog's ID, version, and relative path to the game profile's <code>assetCatalogs</code>, or let the game-profile exporter do it.

Preserve Unity <code>.meta</code> files when moving assets. Catalog keys use their GUIDs and local file IDs. Previews let Vertex display assets without running their scripts; the compiler resolves the original native assets. Only expose content your SDK is allowed to distribute.

== Add an entity type ==

An entity needs both an editor description and a game implementation. Start with one spawn point or trigger and test the full path before adding the rest.

# Create an <code>EntityCatalog</code> from <code>Vertex.Contracts</code> with your SDK ID and version.
# Add a type with a stable ID, display name, placement, properties, and signals. Set <code>importable</code> and its geometry role: <code>none</code>, <code>bounds</code>, or <code>brushes</code>.
# Register a Unity importer with <code>VertexSdkRegistry.Register(sdkId, importer)</code> during editor initialization.
# In that callback, read the validated entity values and add your game's components to the objects in <code>VertexEntityBuildContext.Objects</code>. Resolve asset keys through <code>ResolveAsset</code>.
# Export the catalog and add it to the game profile's <code>entityCatalogs</code>. Place the entity in Vertex, export the map, and verify its runtime behavior.

Property IDs are saved in maps. Keep them stable when changing a display label. Use enum choices, units, bounds, and tooltips so creators can understand a property without reading your source.

Entity signals describe what scripts may call or observe. Declaring <code>open</code> in a catalog does not make a door move; your runtime must implement it. Keep editor metadata and runtime bindings in the same SDK release.

== Run map scripts ==

Vertex supplies the VSig parser, compiler, and runtime. Your game supplies entity bindings and any global events beyond <code>map.ready</code>.

Validate scripts against the exported entity and global-event catalogs during compilation. Store the compiled <code>VSigCompiledProgram</code> in the map. At runtime, initialize <code>VertexScriptHost</code> with that program and the map's entity bindings, then call <code>MarkReady</code> after those bindings are ready.

The host can tick automatically with Unity time. For a game with its own simulation clock, initialize it with <code>automaticTick: false</code> and call <code>Tick</code> from that clock. Dispose the host when unloading the map.

In multiplayer, derive script authority from the running server/client roles. A catalog cannot grant permission to run server actions on a client. Expose commands, variables, and global events deliberately; Grimwar's round events and VMod API do not come with Vertex itself.

== Add build and play actions ==

Register the parts your workflow needs:

{| class="wikitable"
! API !! Responsibility
|-
| <code>VertexSdkRegistry.RegisterCompiler(gameId, version, compile)</code> || Import captured inputs, validate entities and resources, bake required data, and produce a scene or installable package.
|-
| <code>VertexEditorBridge.Register(gameId, version, save)</code> || Save captured sources into the open game project and return a Unity scene path. Honor <code>context.Compile</code> to distinguish saving from saving and compiling.
|-
| <code>VertexSdkRegistry.RegisterCollisionPolicy(id, resolve)</code> || Map your game's collision categories to native layers when you expose collision filters.
|}

The compiler runs through <code>Vertex.Unity.Editor.VertexBuildCompiler.Run</code>. Its <code>VertexBuildContext</code> supplies captured files, progress, cancellation, and result handling. Complete the job with the built scene and pass results; package jobs must also return an audited root containing <code>vertex-package.json</code>.

In the game profile's <code>build</code> settings, declare supported profiles and targets, your package format, and launch arguments. Use <code>{addonRoot}</code>, <code>{packageRoot}</code>, and <code>{mapId}</code> for the supported substitutions. Your game must load that package format and handle those arguments. Set <code>steamAppId</code> to the game's app ID if Steam is required.

For base-game authoring, save sources and generated scenes below <code>Assets/GameContent/Maps/<map_id>/</code>. Saving into the game project does not need a separate platform choice; the game's player build handles its platforms. Add-on export builds the targets declared by your SDK.

== Custom media and other resource types ==

Declare <code>contentTypes</code> for file types your game supports, including extensions, size limits, settings, and asset kind. The SDK owns validation, native conversion, packaging, and runtime loading. An entry in the picker does not create a sound player or video surface by itself.

Use <code>resourceTypes</code> for other source formats, such as game scripts or mission data. Each type names a manifest, its source-file list property, and a starter template. Enable standalone authoring when it also makes sense outside a map.

Ship the resource worker in the SDK and register it under <code>resourceTools</code> for each supported desktop runtime. VSDK uses it for validate/build/test operations. Unity integrations register map-resource validation with <code>VertexSdkRegistry.RegisterResource</code>; the game decides when the resource starts and stops.

Keep these formats game-owned. Another game can use the same Content and resource controls without implementing Grimwar entities or VMods.

== Ship an SDK ==

Distribute matching Vertex/VSDK applications, authoring catalogs and previews, engine packages, a compiler project, and any resource workers. A public <code>.vertexsdk</code> uses <code>compilerInputs</code> for its verified compiler-file inventory and omits the local <code>editorProject</code> connection. The compiler project should contain only the authoring and build code you intend to ship.

Test the SDK from a clean installation with no access to your game checkout. Create a map, import custom media, build every required target, install it into the game, and test an SDK update. Check failure and cancellation too: an unsuccessful build must leave the previous package intact.

For another engine, reuse the portable <code>Vertex.Contracts</code> and <code>Vertex.VSig</code> contracts and implement <code>IEngineAdapter</code> in a trusted engine assembly. Convert coordinates and units at that boundary. There is no finished production Godot adapter in the current distribution.

[[Category:Vertex]]

Vertex/Integrating your game - Revision history

DocumentationBot: Expand game integration guide with step-by-step build, content, and SDK instructions

DocumentationBot: Explain creating a Vertex game connection step by step

DocumentationBot: Clarify custom content navigation and standardize asset examples

DocumentationBot: Version 1