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.

For Grimwar maps, follow Grimwar SDK setup and use the supplied Grimwar.vertexsdk. The steps below are for connecting a game you are developing.

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.

After creating the connection below, you can go straight to Add build and play actions for a first scene build. Materials, entities, scripts, and custom media can be added one at a time afterward.

Create a .vertexsdk file

Create two plain-text JSON files with a text editor such as VS Code or Notepad:

• MyGame.vertexgame describes your game: its name, identifier, Unity version, and available content.
• MyGame.local.vertexsdk tells Vertex where that description and your Unity project are saved. This is the file you select in File → Open game SDK….

Start with an existing Unity project and the Vertex Unity package installed as described in First level in Unity. The examples below make a local connection to that project. You can add materials, entities, and build actions after the connection works.

1. Choose where to save the files

Find your Unity project folder: it contains Assets, Packages, and ProjectSettings. Go up one folder and create an Authoring folder there. The two new files will fit into this layout:

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

Here, MyGame is the parent folder and UnityProject is your existing Unity project. Keep your current folder names; step 3 explains how to use them in the connection file.

2. Create MyGame.vertexgame

Create a file in Authoring, paste the following JSON, and save it as MyGame.vertexgame. Save as plain text and check the full filename: it must end in .vertexgame, with no extra .txt extension.

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

Before saving, set these values for your game:

Field	What to enter
id	An identifier you choose, such as com.yourstudio.yourgame. Keep it stable once maps use it.
name	The name Vertex should display, such as My Game.
version	Your game profile version. You can start with "1"; this is separate from the Unity version.
engineVersion	Your project's exact Unity version. Open ProjectSettings/ProjectVersion.txt and copy the value after m_EditorVersion:. Replace 6000.3.17f1 if your project uses another supported version.

For this first connection, keep entityCatalogs and assetCatalogs as empty lists ([]). They will list your entities, materials, and models later. The sample uses one map unit per metre; defaultMetersPerUnit can be 0.0254 for inches. Keep coordinates as shown: Vertex's Unity importer handles the coordinate conversion.

3. Create MyGame.local.vertexsdk

Create another plain-text file in the parent folder, next to Authoring and your Unity project folder. Paste this JSON and save it as MyGame.local.vertexsdk, with no extra .txt extension. The .local part is a naming convention for this developer connection; the file extension is .vertexsdk.

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

Set game.id and game.version to exactly match the id and version you saved in MyGame.vertexgame.

Path	What it points to
game.path	The game description from step 2. Authoring/MyGame.vertexgame means open the Authoring folder beside this .vertexsdk file, then read MyGame.vertexgame.
compilerProject	Your Unity project folder, which supplies the source for map builds.
editorProject	Your local Unity project for saving maps into the editor. Use the same folder as compilerProject for this setup.

If your Unity project folder is named SpaceGame, replace both "UnityProject" values with "SpaceGame". If you change the game description's filename or folder, update game.path too.

All three paths start from the folder containing MyGame.local.vertexsdk. Use forward slashes (/) even on Windows, and keep the referenced files and folders below that folder. Absolute paths and ../ are not accepted here.

4. Open and check the connection

1. In Vertex, choose File → Open game SDK….
2. Select MyGame.local.vertexsdk.
3. Check the status message. It should start with My Game connected. (using the name from your game description).
4. When creating a new map, select your game. Existing maps retain their own game connections.

Vertex now knows your game's identity, units, and project paths. You can continue the geometry import steps in First level in Unity.

The empty catalog lists add no game-specific materials, models, or entities yet. Continue with Expose materials and models and Add an entity type to supply them. Save to Unity and map builds also need the code described in Add build and play actions; creating these two files does not implement those actions.

After editing either file, use Settings → Game and resources → Reload resources in Vertex. Keep this local developer connection out of public SDK distributions.

If the connection does not open

Problem	Check
The file does not appear in the SDK chooser	Show filename extensions in your file manager. The file must end in .vertexsdk, not .vertexsdk.txt.
Invalid JSON	Save plain text, use straight double quotes, and check commas and brackets against the examples. Copy only the JSON, without surrounding wiki text.
Missing file or compiler project	Check paths from the folder containing .vertexsdk. The project path must reach the existing Unity project containing Assets, Packages, and ProjectSettings.
Unity version mismatch	Match engineVersion to m_EditorVersion in that project's ProjectSettings/ProjectVersion.txt, including the patch version and suffix.
Game ID or version mismatch	Match game.id and game.version in .vertexsdk to id and version in .vertexgame exactly.

Expose materials and models

An asset catalog is the list of Unity materials and models Vertex can offer in its pickers. It also contains previews, so Vertex can show the content without running Unity. Start with one material and one prefab you can recognize.

1. Choose the Unity assets

1. In your Unity project's Project window, create Assets/GameContent/VertexLibrary and put the test material and prefab there.
2. Create Assets/Editor if it does not exist. Inside it, right-click and choose Create → Vertex → Asset catalog profile. Name the asset VertexAssets, giving it the path Assets/Editor/VertexAssets.asset.
3. Select the asset. Set Catalog Id to mygame.base and Catalog Version to 1.
4. Add one entry to Folders. Set Folder to Assets/GameContent/VertexLibrary, with forward slashes and no trailing slash. Enable Materials, Models, and Prefabs for the types you want to expose.
5. Set Ownership to base for assets that your installed game already supplies. Use custom for creator-owned assets that your package builder is allowed to include in an add-on.

Folder rules include subfolders. Keep the first rule narrow: pointing it at all of Assets can expose unrelated content. Preserve the assets' .meta files; their GUIDs form part of the keys saved in maps.

2. Add an export menu in Unity

Create UnityProject/Assets/Editor/MyGameCatalogExport.cs and paste this complete script. It uses the folder layout from Create a .vertexsdk file. It exports the catalog next to your game description and updates that description without removing its other settings.

using System.IO;
using System.Linq;
using UnityEditor;
using UnityEngine;
using Vertex.Contracts;
using Vertex.Unity.Editor;

public static class MyGameCatalogExport
{
    [MenuItem("Tools/My Game/Export Vertex assets")]
    public static void Export()
    {
        var profile = AssetDatabase.LoadAssetAtPath<VertexAssetCatalogProfile>(
            "Assets/Editor/VertexAssets.asset");
        if (!profile)
            throw new FileNotFoundException("Create Assets/Editor/VertexAssets.asset first.");

        var authoring = Path.GetFullPath(Path.Combine(Application.dataPath, "../../Authoring"));
        var gamePath = Path.Combine(authoring, "MyGame.vertexgame");
        var game = GameProfile.Load(gamePath);
        var catalog = VertexAssetCatalogExporter.Export(profile,
            Path.Combine(authoring, "MyGame.vertexassets"));
        game.AssetCatalogs = game.AssetCatalogs
            .Where(reference => reference.Id != catalog.Id)
            .Append(new ProfileReference
            {
                Id = catalog.Id,
                Version = catalog.Version,
                Path = "MyGame.vertexassets"
            }).ToArray();
        VertexAssetCatalogExporter.Publish(gamePath, game.Serialize());
        Debug.Log("Vertex assets exported to " + authoring);
    }
}

If you used different filenames, change the two MyGame.vertexgame/MyGame.vertexassets paths in the script. The Assets/Editor location makes this an editor script; do not attach it to a GameObject.

3. Export and check the pickers

1. Wait for Unity to compile the script. Resolve any red Console errors before continuing.
2. Choose Tools → My Game → Export Vertex assets in Unity.
3. Check that Authoring/MyGame.vertexassets and the exported preview files exist. The Console should report the export folder.
4. In Vertex, choose Settings → Game and resources → Reload resources.
5. Open the material picker and look for your test material. Apply it to a brush. Check the model/prefab picker for the test prefab and place it.
6. Export a .vertexmesh into Unity again. Check that it resolves to the original material and prefab, rather than just matching the preview image.

Re-run the export menu after changing assets. Keep the catalog and its preview files together when distributing them. If a material is missing, check its folder rule and Materials checkbox. If it appears but imports incorrectly, check that the compiler project contains the same assets, .meta files, and catalog profile. Custom shaders may also need a project-specific material preview provider.

For automated releases with several catalogs, VertexGameProfileExporter.Export publishes the catalogs and game description together. The menu above is sufficient for this first local catalog.

Add an entity type

An entity definition adds a choice to Vertex. A Unity importer turns that choice into a working game object. This example adds a point light so you can see the result without writing a player or trigger system.

1. Create the entity catalog

Save the following as Authoring/MyGame.vertexentities.json. Change sdkId if you changed the example game's identifier.

{
  "formatVersion": 1,
  "sdkId": "com.example.mygame",
  "sdkVersion": "1",
  "entities": [
    {
      "id": "point_light",
      "name": "Point light",
      "category": "My Game",
      "placement": "point",
      "geometry": "none",
      "importable": true,
      "properties": [],
      "signals": [],
      "capabilities": 0
    }
  ],
  "globals": [],
  "diagnostics": []
}

In MyGame.vertexgame, replace the existing entityCatalogs value ([]) with this array. These paths start beside MyGame.vertexgame, so there is no Authoring/ prefix here.

[
  {
    "id": "com.example.mygame",
    "version": "1",
    "path": "MyGame.vertexentities.json"
  }
]

2. Add the Unity importer

Save this as UnityProject/Assets/Editor/MyGameEntityImport.cs. The registration ID must match the catalog's sdkId.

using System.IO;
using UnityEditor;
using UnityEngine;
using Vertex.Unity.Editor;

[InitializeOnLoad]
public static class MyGameEntityImport
{
    static MyGameEntityImport()
    {
        VertexSdkRegistry.Register("com.example.mygame", Import);
    }

    private static void Import(VertexEntityBuildContext context)
    {
        foreach (var entity in context.Entities)
        {
            if (entity.Entity.TypeId != "point_light")
                throw new InvalidDataException("Unknown entity: " + entity.Entity.TypeId);
            var light = context.Objects[entity.Id].AddComponent<Light>();
            light.type = LightType.Point;
            light.range = 10;
            light.intensity = 2;
        }
    }
}

Vertex has already created and positioned each object's transform. The importer adds the native component to that object. The range above is in Unity metres. Changing these values changes future imports; this first entity has no editable properties in Vertex yet.

3. Place and test it

1. Wait for Unity's scripts to compile, then reload resources in Vertex.
2. In Create, choose Point light under My Game and place it near a floor or wall.
3. Export a .vertexmesh into your Unity project and place the imported prefab in a scene. Enable its root if it is inactive.
4. Expand the hierarchy and select the entity. It should have a Unity Light component with range 10 and intensity 2. Check it with Scene lighting enabled.

If the entity appears in Vertex but Unity says its SDK is missing, the catalog was loaded but the importer was not registered. Check the Assets/Editor script, Unity Console errors, and the exact registration ID.

Next, add catalog properties such as range or color and read their validated values in the importer. Use context.ResolveAsset for asset-key properties. Keep entity and property IDs stable: maps store them. Add signals only when the runtime implements them; declaring an open input does not give a door any behavior.

Run map scripts

Do this after an entity imports correctly and its game behavior works without scripting. Vertex supplies the VSig language and runtime; your game must connect script inputs and outputs to its components. The point-light example above does not yet supply script bindings.

1. Define and implement one signal

1. Choose one behavior, such as enabling a light or opening a door. Add the input's name, value type, and authority to that entity's catalog definition.
2. In your game's runtime code, implement IEntitySignalRuntime for that component. Its input handling must call the actual game behavior.
3. Create an EntityDescriptor for each imported entity, using its persistent map/object IDs and the catalog's signal contract. Keep a dictionary from those descriptors to their runtime bindings.
4. Re-export/reload the catalog. Follow Map logic to write a small script that calls the input from map.ready.

The expected result at this stage is a valid script in Vertex. Runtime behavior still depends on the next two steps.

2. Compile the script with the map

1. Extend your Unity compiler to read the captured entry script at context.PathFor(context.Job.Script) and its declared source dependencies.
2. Parse with VSigParser and validate with VSigProgramValidator, using the same entity descriptors and global-event catalog your game exposes. Stop the build on errors.
3. Convert the valid program with VSigCompiledProgram.FromProgram and store its serialized data with the built map, using a game-owned component or asset. A .vsig file beside a scene is not automatically executed.

Resolve imports from the captured source set, so the build uses the versions captured when it started. Do not read an unrelated live script folder halfway through a build.

3. Start the runtime and check the result

1. When your game loads the map, create or enable a GameObject with VertexScriptHost. It must be active before initialization.
2. Call Initialize(compiledProgram, bindings, capabilities) after the entity bindings exist. The arguments are the saved compiled program, your descriptor-to-runtime dictionary, and the VSigHost containing your game's allowed operations and globals.
3. Call MarkReady() once the map is ready for scripts. This emits map.ready.
4. Load the test map and confirm that the chosen light or door responds. Then deliberately misspell the input in the source: the next build should fail with a useful error.

The host advances automatically using Unity time. If your game owns the simulation clock, pass automaticTick: false and call Tick(seconds) from that clock instead. Disabling or destroying the host disposes its runtime; re-enabling requires initialization again.

For multiplayer, derive authority from the running server/client roles. Global events other than map.ready, console commands, and variables need game-owned bindings. Grimwar's round events and VMod API are not supplied to another game by installing Vertex.

Add build and play actions

Start with a scene build: Vertex captures your map, runs Unity in a separate project, and produces a .unity scene you can inspect. This checks your connection and compiler before you implement an installable add-on or a game launcher.

Building a map does not build your game's executable. You still build your game with Unity's normal player build. Play in Game later loads a built map into an existing game executable.

1. Understand the three actions

Action	Where it runs	What you must supply
Build scene / your export label	A separate Unity process using a private copy of the compiler project	A build object in .vertexgame and an editor script registered with VertexSdkRegistry.RegisterCompiler. Steps 2–5 below provide a first example.
Save to Unity / Save & Compile to Unity	Your already-open Unity editor	An editorProject connection, build.editorSaveLabel, and a separate VertexEditorBridge.Register callback. See step 6.
Play in Game	The package compiler, then your installed game	Working package export, build.launchArguments, and a game that can load the package. See steps 7–8.

The JSON supplies names and supported choices. It does not contain C# or a shell command, and it does not generate the Unity implementation. Put the implementation in your own Assets/Editor scripts; keep the supplied Vertex package unchanged.

2. Add build settings to MyGame.vertexgame

Open Authoring/MyGame.vertexgame. Keep the existing identity, engine version, and catalogs. Add a comma after the last existing field, then add the build field shown here before the final closing brace. This block shows only the new field; it is not a replacement for the whole game description.

{
  "build": {
    "profiles": ["Preview"],
    "targets": [
      { "id": "StandaloneWindows64", "name": "Windows", "platform": "windows" },
      { "id": "StandaloneOSX", "name": "macOS", "platform": "macos" },
      { "id": "StandaloneLinux64", "name": "Linux", "platform": "linux" }
    ],
    "exportLabel": "Build scene"
  }
}

profiles is the list shown in the build profile selector. Preview is a name passed to your compiler, not an automatic choice of lighting quality. The target IDs above are the supported Unity build targets; their name values are the labels shown to users. Remove targets your game will not support.

Leave packageFormat, launchArguments, and editorSaveLabel absent for now. This example produces a scene and does not advertise an unimplemented save or play action. Keep MyGame.local.vertexsdk as created earlier.

3. Register a first scene compiler

Create UnityProject/Assets/Editor/MyGameVertexBuild.cs and paste the following. Replace the registration's com.example.mygame and 1 if you changed the game ID or version. Both must match MyGame.vertexgame exactly.

using System.IO;
using System.Linq;
using UnityEditor;
using UnityEditor.SceneManagement;
using UnityEngine;
using Vertex.Unity.Editor;

[InitializeOnLoad]
public static class MyGameVertexBuild
{
    static MyGameVertexBuild()
    {
        VertexSdkRegistry.RegisterCompiler("com.example.mygame", "1", Compile);
    }

    private static void Compile(VertexBuildContext context)
    {
        if (context.Job.Package)
            throw new InvalidDataException("This example builds scenes, not add-on packages.");
        if (context.Job.Game.Baking != null ||
            (context.Job.Resources?.Length ?? 0) != 0 ||
            (context.Job.Content?.Length ?? 0) != 0)
            throw new InvalidDataException("Add baking, resource, and custom-media support before building this map.");
        if (File.ReadLines(context.PathFor(context.Job.Script))
            .Any(line => line.Trim().Length > 0 && !line.TrimStart().StartsWith("#")))
            throw new InvalidDataException("This first compiler needs a map with no VSig script.");

        context.CheckCanceled();
        context.Policy = "mygame.scene-only.v1";
        const string scenePath = "Assets/VertexBuild/Output/Map.unity";
        context.PrepareScenePath(scenePath);
        var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(context.Job.Map);
        if (!prefab)
            throw new InvalidDataException("Map import failed; inspect the Unity build log.");

        var scene = EditorSceneManager.NewScene(NewSceneSetup.EmptyScene, NewSceneMode.Single);
        var map = (GameObject)PrefabUtility.InstantiatePrefab(prefab, scene);
        map.SetActive(true);
        context.Report(0.8, "Saving the imported map scene…");
        if (!EditorSceneManager.SaveScene(scene, scenePath))
            throw new IOException("Could not save " + scenePath);
        context.Complete(scenePath, new[] { "geometry-import" });
    }
}

Wait for Unity to compile it and check the Console for errors. There is no component to attach or menu to click: InitializeOnLoad registers the callback whenever this Unity project loads, including in Vertex's build process.

The example imports geometry and any entities whose importers you registered. It deliberately rejects scripts, custom media, resource attachments, package jobs, and declared bake policies until you implement them. It adds no player, camera, or game bootstrap. Use a small test map with a floor and walls for the first build.

Vertex starts Unity through the fixed Vertex.Unity.Editor.VertexBuildCompiler.Run entry point. That code verifies the captured inputs, imports the map as a prefab, and then calls your registered Compile method. You do not put that method name in the JSON.

4. Configure the machine and build

1. In Unity Hub, install the exact editor version recorded in engineVersion, with the build support module for your chosen target. Activate its Unity license. The current Unity build entry point also requires a graphics-capable machine, even for this simple scene example.
2. In Vertex, reload resources. Create or open a map connected to My Game, then save it as arena_test.vertex in a folder you own.
3. Open Build. You should now see Build scene, the Preview profile, and the targets you declared.
4. Expand Advanced settings. Check Engine executable: it must be the matching Unity editor executable or Unity.app, not Unity Hub or your game's executable.
5. Check Compiler template: it must point to your UnityProject folder, containing the new compiler script and the Vertex package. The local SDK connection normally fills this in.
6. Set Build directory to a separate writable location, such as MyGame/VertexBuilds. Do not use your Unity project itself or a folder inside it.
7. Choose your machine's target for the first test, select Preview, and click Build scene. Watch the progress and diagnostics in the Build panel.

Unity works on a captured copy of the project. The first build can take longer while Unity imports that copy. Save changes to your Unity scripts and assets before starting; changes made after the snapshot belong to the next build.

5. Find and inspect the result

1. Wait for the successful build result. Choose Open current output. For this scene-only example, it opens the retained build workspace.
2. Find Assets/VertexBuild/Output/Map.unity inside it. The captured input is Assets/VertexBuild/Input/Map.vertexmesh; logs and result information are under VertexJob.
3. After the build process has exited, open that workspace as a separate project with the matching Unity version. Open Map.unity, select the map root, and press F in the Scene view to frame it.
4. Check the meshes, materials, and colliders. Add your game's player/camera/bootstrap creation to your compiler when you are ready to make this scene playable.

Keep the whole workspace when inspecting it: the scene references imported assets elsewhere in the project. It is a build result, not the folder to distribute to players. Make further edits to the original .vertex map and compiler code, then rebuild.

Once this works, add your required validation, VSig compilation, navigation, lighting, and other bake steps. Set a policy identifier that describes the checks your compiler actually performs, and report only completed passes in Complete. Reporting a pass name does not perform that pass.

If your game exposes collision filters, register VertexSdkRegistry.RegisterCollisionPolicy(id, resolve) during editor initialization. The resolver maps your game's collision categories to Unity layers; the importer needs that registration to apply the filters saved in a map.

6. Optionally save into the open Unity project

This is a separate integration for developers working on base-game maps. It avoids opening a separate output project each time.

1. Keep editorProject in the local .vertexsdk pointing to your development project. Add "editorSaveLabel": "Save to Unity" inside the game's build object.
2. In an Assets/Editor script, register VertexEditorBridge.Register(gameId, version, save) during initialization. The save callback takes a VertexEditorMapContext and must return the path of a saved Unity scene, starting with Assets/.
3. In that callback, use context.Job and context.PathFor(...) to read the captured map and source files. Copy the inputs needed by the saved map out of the temporary request directory. For example, organize them below Assets/GameContent/Maps/arena_test/ and create Authoring.unity there.
4. Inspect context.Compile. For Save to Unity, save the authoring data. For Save & Compile to Unity, also run your game's validation and compilation steps. Return the scene that was actually saved. Preserve previous output if validation or cancellation fails.
5. Open the development project, exit Play Mode, and save any modified Unity scenes. Reload resources in Vertex, then try Save to Unity. Confirm the new scene and its dependencies exist under Assets.

The scene-build callback from step 3 does not implement this callback; adding the label alone is insufficient. Save actions do not need the export platform selector: your normal game player build handles platforms for base-game assets.

7. Implement an installable package

Do this before enabling Play in Game. A standalone Unity game cannot load an arbitrary editor .unity file from disk. Your game needs a supported runtime format, such as an add-on containing built scene bundles, and a loader for it.

1. Choose a package format ID, for example mygame.addon.v1. Implement how your game finds, validates, loads, and unloads a map in that format.
2. Extend the compiler to handle context.Job.Package. Build the scene, compile its scripts/resources, run required bakes, and build its platform-specific bundles or other runtime data.
3. Write the package below VertexPackage/ in the private build workspace. Include vertex-package.json, serialized from Vertex.Contracts.PackageManifest. It records the map/game identity, input hash, profile/target, format, file hashes, and asset ownership/bundle membership. This is separate from any manifest your game's loader needs.
4. Keep installed base assets out of the package; include permitted custom assets and generated map data with their required dependencies. Audit the actual output and bundle membership rather than recording the intended contents.
5. Finish with context.Complete(scenePath, completedPasses, packageRelativePath). The package path must start with VertexPackage/. Vertex checks the manifest and output receipts before replacing the current result.
6. Add "packageFormat": "mygame.addon.v1" inside build and change exportLabel to Export add-on. Reload resources and export a small map. Use Open current output to inspect the package, then Install current package to test installation.

Do not add packageFormat while still using the scene-only compiler: it changes export requests into package jobs, which that example rejects. A successful export does not upload to Steam Workshop or publish your game.

8. Connect Play in Game

After the package loads successfully in your game, add these fields inside the existing build object. Keep its profiles, targets, export label, and package format. This block again shows only the additional fields.

{
  "addonDirectory": "MyStudio/MyGame/addons",
  "launchArguments": ["--addon-root", "{addonRoot}", "--map", "{mapId}"]
}

--addon-root and --map are example arguments for your game's own command-line parser. Unity and Vertex do not automatically implement them. Use the argument names your game actually handles; put each argument and value in a separate array entry.

Substitution	Value passed to your game
{addonRoot}	The parent folder containing installed add-on packages.
{packageRoot}	The specific installed package folder for this map.
{mapId}	The public map ID derived from the saved filename, such as arena_test.

1. Reload resources in Vertex. Play in Game should now appear.
2. In Build → Advanced settings, choose the already-built Game executable and the Add-on folder your game reads. addonDirectory supplies a default relative to the user's local application-data folder; it is not relative to the SDK.
3. Choose a target matching the machine that will run the game. Close any game instance that still has the old bundles loaded.
4. Click Play in Game. It builds the current inputs, installs the successful package, then launches that executable with the configured arguments.
5. Confirm your game opens arena_test. If the game opens its usual menu, check its command-line handling and map-loading logs. Starting the process does not prove that the game loaded the requested map.

Set steamAppId to the game's Steam app ID only if the game requires Steam; omit it otherwise. Executable paths belong in each user's local settings, not the shared game description. Add a Release profile and allTargetsPackageProfiles only when the compiler implements the corresponding checks and can build every required target.

If building does not work

Symptom	What to check
No build choices	The connected game's .vertexgame needs a valid build object. Reload resources, then check that the map is connected to that game.
Build button disabled	Save the map first. Finish or cancel any running job and resolve any local-settings error shown in Build.
“Install the compiler binding…”	The compiler script must be inside the project selected as Compiler template. Resolve Unity compilation errors; match the registered game ID and exact version. A script only present in another open project will not register in this build.
Unity version, license, target, or graphics error	Match engineVersion, activate that editor, install the selected target's support module, and use a graphics-capable worker. The build entry point rejects -nographics.
A script, media, or package request is rejected by the example	The first compiler supports scene import only. Test a plain map, then implement the named feature before advertising it in the game profile.
Waiting for Unity during Save	Open the project named by editorProject, exit Play Mode, save dirty scenes, and check that the separate save callback is registered.
Play is missing	launchArguments must be present, and they require packageFormat. First get package export and your game's loader working.
Build fails or is cancelled	Read the first build diagnostic and the retained Unity log. The previous successful output stays available; Play does not launch that older output as a substitute for the failed build.

Custom media and other resource types

These are optional. Add them after the plain-map build works, one type at a time. There are two different lists in MyGame.vertexgame:

• contentTypes describes imported files such as sounds, images, models, and data. They appear in Content and use stable asset keys.
• resourceTypes describes a source folder with its own JSON manifest and declared files, such as a mission or a game-specific script module. It can be attached to a map and, when supported, authored separately through VSDK.

1. Declare one media type

For example, add the following field at the top level of MyGame.vertexgame if your game will support WAV sounds. This is an additional field, not a complete game description.

{
  "contentTypes": [
    {
      "id": "sound",
      "name": "Sound",
      "kind": "audio",
      "extensions": [".wav"],
      "maximumBytes": 16777216,
      "settings": []
    }
  ]
}

1. Reload resources. Open Content and import a small WAV file using the new Sound type.
2. Check the map's source folder: content.json records the asset and its settings, and Content/ holds its source file. The example limits one file to 16 MiB.
3. Extend your compiler to process the captured catalogs in context.Job.Content, validate the allowed format/size, and include or convert the needed audio data into the runtime package.
4. Add an asset-key property to an entity, or a game API that accepts the sound key. Implement how the runtime resolves and plays it.
5. Build, load the map, and trigger the sound. Merely seeing it in Content confirms authoring registration, not runtime playback.

Use additional settings entries for game-owned choices such as volume or looping. Your importer and runtime must interpret them. See Custom content for the creator's import, replacement, and dependency workflow.

2. Add a manifest-based resource when needed

1. Choose a stable resource ID, for example mission, and define the format your game will read.
2. Add a resourceTypes entry to .vertexgame. It needs id, name, manifest, filesProperty, and template. For a mission, these could be mission, Mission, mission.json, and sourceFiles.
3. Supply the template as an array of path/content objects, including the manifest itself and every starter source file. The manifest's sourceFiles array lists relative filenames; {{id}} in template text is replaced with the new resource ID.
4. Register VertexSdkRegistry.RegisterResource("mission", validator) in your Unity editor integration. In your compiler, call VertexSdkRegistry.CaptureResources(context.Job, context.Root) to obtain validated captured resources, then compile/store them in your map's runtime format. Registration alone does not add this call to a custom compiler.
5. Reload resources and use Settings → Game and resources → Mission → Create to make a test resource. Edit and save its declared files, then build the map. Check that invalid input fails validation and that valid input reaches your game.

For standalone authoring, also implement a resource worker executable and add its paths under resourceTools in .vertexsdk, one per supported desktop runtime. Set the resource type's standalone flag only when that workflow is supported. VSDK uses the worker for validate/build/test actions; the game still decides when the resource starts and stops.

Ship an SDK

Do this after building and loading a map works on your development machine. The release must also work for someone who has none of your project folders. A .vertexsdk file is the entry point to the distribution; it does not contain the compiler or catalogs itself.

These steps package your own game integration. Creators should install Vertex/VSDK from Vellocet's official distribution. Bundling Vellocet's tools, Unity package, or source with your SDK requires prior written permission; the license's compiled-runtime exception covers finished games and projects. Credit Software by Vellocet Corporation as required by the included license.

1. Assemble a separate distribution folder

1. Create a clean compiler project containing your registered compiler, entity importers, needed Unity packages, catalog profiles, and authorized build assets. Keep local caches, credentials, and unrelated game source out of that project.
2. Copy the game description, entity/asset catalogs, and preview files into Authoring/, preserving the relative paths recorded in the game description.
3. Document the matching Vertex/VSDK versions creators must install. Include your own resource workers for the platforms you support, and document how to install any dependencies you cannot bundle.
4. Generate Compiler.inputs.json from the finished compiler tree using Vertex.Contracts.BuildInputs. Each file entry records its relative path, byte count, and SHA-256 hash. Generate it in your release tooling; do not hand-maintain hashes or include the compiler's generated Library directory.
5. Create a public MyGame.vertexsdk using the example below. Include resourceTools too if your game provides workers. Keep the developer-only MyGame.local.vertexsdk out of this distribution.

MyGameSDK/
  MyGame.vertexsdk
  Compiler.inputs.json
  Authoring/
    MyGame.vertexgame
    MyGame.vertexassets
    MyGame.vertexentities.json
    previews/
  Compiler/
    Assets/
    Packages/
    ProjectSettings/

The catalog/preview filenames above correspond to the earlier examples; keep the actual exported preview folders.

{
  "formatVersion": 1,
  "game": {
    "id": "com.example.mygame",
    "version": "1",
    "path": "Authoring/MyGame.vertexgame"
  },
  "compilerProject": "Compiler",
  "compilerInputs": "Compiler.inputs.json"
}

The public connection omits editorProject, because a creator does not have your development checkout. Remove build.editorSaveLabel from its game description as well. The inventory lets Vertex verify and prepare the compiler cache; regenerate it whenever any compiler file changes.

Review what your release tooling copies. The Vertex application is compiled, but copying a Unity package directory can include that package's C# source. A public compiler project should contain only the code and assets you intend and have permission to distribute.

2. Test it as a creator

1. Copy the distribution to a fresh location or machine. Make your development checkout unavailable to the test so missing dependencies cannot resolve accidentally.
2. Install the pinned Unity version and required modules, then open the SDK through VSDK or File → Open game SDK… in Vertex.
3. Create a new map outside the SDK folder. Test the supplied material, entity, script, and custom-media workflows.
4. Build every supported target/profile, install the result, and launch the actual game. Confirm it loads the newly built map.
5. Introduce an invalid source, then cancel a separate build. Both should preserve the last successful output; a failed play request must not launch an older package.
6. Replace the SDK with a new release, reload resources, and rebuild the same map. Its authored sources and stable asset/entity references should still work.

Record the matching editor, package, compiler, and catalog versions in your release process. Ship them together rather than replacing one executable in an older SDK.

Using another engine

The JSON can describe another engine, but it cannot install one into Vertex. An engine developer must implement IEngineAdapter in a trusted engine assembly and register it in the desktop application. Reuse the portable Vertex.Contracts and Vertex.VSig libraries, and convert coordinates and units at that boundary. There is no finished production Godot adapter in the current distribution.