Vertex/Integrating your game

Vertex · Getting started · Editing · Custom content · Map logic · Game integration

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 com.vellocet.vertex Unity package. The Grimwar SDK includes that package under Compiler/Packages/com.vellocet.vertex/; 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 6000.3.17f1.

1. Add the Vertex package through Window → Package Manager → Add package from disk… and select its package.json. Keep the package folder available to the project.
2. Create a small map in Vertex without a game connection. Use plain brush geometry for the first import.
3. Choose File → Export compiled meshes… and save a .vertexmesh under your Unity project's Assets/GameContent/Maps/arena_mycustommap/ folder.
4. 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.
5. Add your game's player, camera, and startup objects, then test movement and collision.

Keep the .vertex 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:

File	What you supply
.vertexgame	Game identity, units, exact engine version, catalog references, and optional build policy.
.vertexassets	Available materials, models, and other native assets, with previews and ownership.
Entity catalog JSON	Placeable entity types, editable properties, and script inputs and outputs.
.vertexsdk	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 defaultMetersPerUnit to your preferred authoring scale. A value of 1 means one map unit per metre; 0.0254 means inches.

A minimal profile with no catalogs or build commands is:

{
  "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": []
}

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

MyGame/
  MyGame.local.vertexsdk
  Authoring/MyGame.vertexgame
  UnityProject/Assets/
  UnityProject/Packages/
  UnityProject/ProjectSettings/

MyGame.local.vertexsdk:

{
  "formatVersion": 1,
  "game": {
    "id": "com.example.mygame",
    "version": "1",
    "path": "Authoring/MyGame.vertexgame"
  },
  "compilerProject": "UnityProject",
  "editorProject": "UnityProject"
}

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

1. In Unity, create a Vertex → Asset catalog profile asset.
2. Set a stable catalog ID and version, such as mygame.base and 1.
3. Add folder rules for the assets creators can use. Mark installed game assets as base and creator-owned assets that may ship in add-ons as custom.
4. Export the profile with VertexAssetCatalogExporter.Export, or publish it together with the game profile using VertexGameProfileExporter.Export.
5. 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:

using UnityEditor;
using Vertex.Unity.Editor;

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

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

Preserve Unity .meta 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.

1. Create an EntityCatalog from Vertex.Contracts with your SDK ID and version.
2. Add a type with a stable ID, display name, placement, properties, and signals. Set importable and its geometry role: none, bounds, or brushes.
3. Register a Unity importer with VertexSdkRegistry.Register(sdkId, importer) during editor initialization.
4. In that callback, read the validated entity values and add your game's components to the objects in VertexEntityBuildContext.Objects. Resolve asset keys through ResolveAsset.
5. Export the catalog and add it to the game profile's entityCatalogs. 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 open 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 map.ready.

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

The host can tick automatically with Unity time. For a game with its own simulation clock, initialize it with automaticTick: false and call Tick 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:

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

The compiler runs through Vertex.Unity.Editor.VertexBuildCompiler.Run. Its VertexBuildContext 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 vertex-package.json.

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

For base-game authoring, save sources and generated scenes below Assets/GameContent/Maps/<map_id>/. 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 contentTypes 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 resourceTypes 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 resourceTools for each supported desktop runtime. VSDK uses it for validate/build/test operations. Unity integrations register map-resource validation with VertexSdkRegistry.RegisterResource; 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 .vertexsdk uses compilerInputs for its verified compiler-file inventory and omits the local editorProject 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 Vertex.Contracts and Vertex.VSig contracts and implement IEngineAdapter in a trusted engine assembly. Convert coordinates and units at that boundary. There is no finished production Godot adapter in the current distribution.