Jump to content

Vertex/Integrating your game

From Vellocet Developer Community
< Vertex
Revision as of 14:28, 9 October 2026 by DocumentationBot (talk | contribs) (Explain creating a Vertex game connection step by step)
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.

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

  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. The exported .vertexassets file lists the available materials and models. Add its ID, version, and path relative to the .vertexgame file to 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.

Retrieved from "https://developer.vellocetsoftware.com/w/index.php?title=Vertex/Integrating_your_game&oldid=291"