Map Studio manual

The Map Studio turns a 3D model - or a few sentences - into a SogaCity map that players can download. You work in this web page. Unity does the heavy work in the background; you never open it.

Your first map in 10 minutes

Use the built-in sample to see the whole way once, from nothing to a map in the game.

1. Open the Map Studio: http://localhost:5280 (see setting it up if it does not open).
2. Step 1, card Describe a map: press Use the sample. The "Neon Outpost" appears in 3D at once.
3. Type a map id (for example my_outpost) and a name, then press Build this map. Wait about 15 seconds - the bar at the bottom shows what the server is doing.
4. You are now in Step 2 · Tags. Turn the map with the mouse. Press Bake preview (server): the walkable floor turns green and problems show as red pins (the sample has none).
5. Look at Step 3 · Markers: the sample already has every kind.
6. Step 4: press Bake & package on the server (about 30-60 seconds). The 6 files appear.
7. Press Submit for review. Switch to Owner (top right), choose This PC - game map cache, press Approve & publish.
8. Start the game in the Unity Editor and pick your map in the map list (see play your map).

Setting it up (once, by the SogaCity team)

What the computer needs

• Unity 2021.3.45f2 (exactly this version) with Windows and Linux build support - the files players download must be built by the same Unity as the game.
• .NET 10 SDK and this repository.

First time

Run these from the repository folder (D:\sogacity_game_mode_test), not from inside MapStudio:

MapBuildProject/sync-from-game.sh       # copies layers, render settings and the game core into the map project
dotnet run --project MapStudio          # starts the Map Studio -> open http://localhost:5280

Already inside the MapStudio folder? Then just type dotnet run. Only one Map Studio can run at a time (it uses port 5280).

And once, to collect the textures of the game's maps into the material library (needs Python with Pillow; run it again when a map gets new materials):

python MapStudio/tools/build_material_library.py

Run the sync again after Sogacity > Rebuild Sim DLLs or after changing layers / render settings in the game project. The first map job takes a few minutes (Unity prepares the map project); after that a job takes seconds.

Choosing the AI

"Describe a map" and "Edit with AI" have an AI list and a Model list. The Model list shows every model that AI offers your key (the studio asks the service; newest first). A name that is not listed: pick Other model… and type it. The studio remembers your choice.

All AIs get the same instructions and must answer with the same layout format, so the checks, the 3D preview and the build work the same for every one. How good the maps are depends on the model - try a short description first. The list (names, addresses, models) is in MapStudio/appsettings.json under Ai:Providers; any service that speaks the OpenAI chat API (OpenRouter, DeepSeek, a company server...) can be added there with its BaseUrl.

Settings (optional)

Copy MapStudio/appsettings.Local.json.example to MapStudio/appsettings.Local.json and fill in what you need. Never commit that file (git ignores it).

Restart the Map Studio after changing settings.

Step 1 · Source

Upload a 3D model

• Formats: .glb (best: textures are inside the file), .gltf (with its .bin and images), .fbx .obj .dae .3ds, up to 500 MB.
• Which formats carry their textures inside? .glb always; .fbx only when exported with "Embed Media" (Blender: Path Mode Copy + the embed button). .gltf, .obj, .dae and .3ds keep textures as separate files - add them in the Textures field.
• glTF files using Draco or KTX compression are not supported yet - export them without compression.
• Textures (for the real look): in the Textures field select all the model's image files at once (.png .jpg .tga .tif .psd). Or upload one .zip with the model and its textures instead. A model alone works, but comes out grey.
• Forgot the textures? Open the map, step 2, Add textures: the model is imported again with them and your tags stay. Build again afterwards so players get the new look.
• Map id: lower case letters, digits and _ (it becomes the file names). Name: what players read in the map list.
• Add a flat ground: for a model without its own ground (a single building), type a size in metres, e.g. 80.
• Scale: 1 unit in the model = 1 metre in the game. A door should be about 2 m tall.

The server imports the model and tags every object automatically (about 10-20 seconds). You check those tags in step 2.

Describe a map

Write what you want, press Draw the layout (about a minute), and look at it in 3D. Not right? Write what to change under Change it ("make the outer walls taller", "add a second floor to the barracks") as many times as you like. When it looks good, press Build this map.

Edit a layout by hand

Any layout on screen (from the AI, a sample or a file) has Edit by hand; a map you built from a layout has Edit layout on the 3D view. Then:

• Click a part (a wall, a platform, a rock…) or a marker to select it. Drag the coloured handles: W move, E turn, R size.
• The panel shows its values: name, tag, material (Texture… picks one from the library or a pattern), position, turn, sizes, copies.
• Add: wall, floor, platform, crate, tower, stairs, ramp, arch, curved wall, wall line, rock, hill, light - it appears where the camera looks.
• Ctrl+D copy, Del delete, Ctrl+Z undo, Ctrl+Y redo, Esc deselect.
• Done? Build this map - or for a map you are editing, Rebuild this map (its layout is the source again: markers you placed in step 3 are replaced by the layout's).

Paint the ground

In Edit by hand, under Paint the ground: pick a brush (grass, sand, dirt, cobble, stone tiles, water, or Other… for any texture), then Stroke and drag on the ground for a band (a path, a beach, a trail), or Area and drag round a shape to fill it (a lawn, a plaza, a pond). The slider sets the width; untick walkable for things only to look at. While painting, the left mouse paints - right-drag moves the view, the wheel zooms. Stop painting to select things again. Each stroke is a part you can move, delete or undo.

Props: real 3D models

In Edit by hand, Prop… opens the props: lamps, benches, barrels, containers, billboards, cars, palms… from the game itself, with pictures, groups and a search. Click one to place it; move, turn and size it like any part. The AI uses them too. A prop's tag decides what heroes do with it (small ones are low cover, tiny ones decoration) - change it in the panel.

Besides the game's own models there are three free CC0 packs from Kenney: nature (trees, pines, bushes, grass, flowers, rocks, logs…), castle (walls, towers, gates…) and graveyard (gravestones, crypts, fences…) - pick the group in the props window. Grass and flowers are decoration (heroes walk through them).

+ Add your model (in the props window) adds your own: a GLB (best - textures inside), glTF with its .bin, FBX or OBJ with its texture pictures, or one .zip. Free models: Sketchfab (CC0 / CC-BY), Kenney, Quaternius, Poly Pizza. The server imports it (a minute the first time); then it is a prop like the others. The ✕ removes one of yours.

Layout styles

Under the description, Layout style tells the AI what kind of map to make: City streets, Canyon / valley, Islands & bridges, River city, Fortress, Multi-level, Ruins, Maze / dungeon path and Castle climb (for Dungeons - climb a castle level by level, a portal fight on each level, the boss on the top), Spaceport, Hub & spokes, Arena. Auto lets the AI choose from your words; Surprise me picks a different style each time. The ground is not always a square either: it can be round, long, any outline, or no ground at all (islands, river banks). Use a sample has a list: Castle Climb (a Dungeon you climb to the boss), Crater Ring (round arena), River District (a river city with bridges), Neon Outpost (boxes only).

Rounded and natural parts

A layout is not only boxes. The AI can also use: curve (a curved wall or a full ring - round arenas), path (a wall or walkway that follows points, with rounded corners - canyons, organic city walls), shape (any outline: odd-shaped platforms, plazas, islands, pools), ramp (a slope you walk up), rock (natural boulders, every one different) and hill (a smooth mound you can walk on). Ask for them in your description ("a round arena", "winding canyon walls", "rocks for cover", "a hill in the west") - press Use the sample to see a map that uses all of them (Crater Ring).

Add your own textures

Open Material library and press + Add your textures: pick one or more pictures (PNG or JPG - a tileable texture works best), give each a name and say how many metres one copy covers ("repeats every 2 m"). They join the library under custom: the AI can use them (name them in your description, e.g. "walls: my_red_bricks"), and so can the Texture… button of the tag list. The ✕ on one of your textures removes it. Besides the game's materials there are 21 patterns made on the fly in any two colours, among them wood planks, cobble, sand, grass, dirt, rock, rust, carbon, marble, lava, water and circuit.

Textures for described maps

The AI builds with the real textures of SogaCity's maps (concrete and metal panels, diamond plate, roads, glass, grids, the city's ad screens...) and with patterns made on the fly in any colour (panels, plates, grating, bricks, tiles, hazard stripes, hex, grid, concrete). Press Material library to see them all; click one to copy its name and put it in your description, e.g. "walls: metalpanel0, floor: diamond_plate_base_color, the boss hall in dark red panels pattern". The 3D preview shows the textures before you build.

Notes under the layout tell you what was fixed automatically (stairs too steep, walls too thin...). Save the layout file keeps your layout; Load a layout file brings it back - also without an AI key.

Your maps

Click a map to continue it. The coloured word shows its state: draft, waiting for review, sent back, published.

Model size & position

In the right column, Model size & position shows how big the uploaded model is. Scale is relative to the model as you uploaded it (2 = twice that size, 0.5 = half), Turn rotates it, centre moves its middle to the map's centre with its floor at height 0 (use it for models that arrive far away or up in the air). Markers and the AI's additions move with it. Heroes are about 1 m wide and 2 m tall: corridors should be 4 m or more. The AI can do this too - "make the map twice bigger".

The studio checks the size for you. When a map is too small (under ~80 m across), too big (over ~600 m), or far from the centre / up in the air, the box lights up yellow with the reason and a suggestion (for example "scale 2.25 and centre"). Use suggestion fills it in; press Apply size & position to do it. The Map status column shows the same as a "Size" line.

Edit a map with AI (uploaded or generated)

Open the map, then use the Edit with AI box in the right column. Write what you want, for example:

The AI looks at your map from above (with a metre grid) and reads its tag list, floors and walls. It answers with additions - new walls, stairs, platforms, portal arches, cover, lights, textures from the library - plus markers to place and tag changes it suggests. They are drawn over your map in 3D. Not right? Write what to change and press Ask the AI again. Happy? Apply to the map: Unity adds them (about 10 seconds) and the map goes on as usual - check the tags, Bake preview, then Bake & package.

A new edit replaces the earlier additions (the AI is told what they were, so ask it to keep what you like). Save edit file keeps an edit; Load edit file brings it back without using the AI.

Step 2 · Tags

The auto-tagging is already done when you get here: it runs by itself when the model is imported. Each row shows the automatic tag and, in grey, why it was chosen ("auto: mostly flat, 0.3 m tall"). Your job is to check the rows and fix the wrong ones. Maps built from a description are tagged from their layout instead ("from the layout").

How to change a tag (3 clicks)

1. Click the object in the 3D view (or its row in the list). It glows cyan - together with every object of the same kind.
2. A bar with 6 coloured buttons appears over the 3D view: Floor · Wall · Jumpable · Stairs · Ignore · Floor + walls. Click the right one - or press 1 to 6. It is saved at once and the colour changes.
3. A texture for this kind of object: in the same bar press Texture…. The material library opens: click a material of the game's maps, or open patterns and pick one (it uses the two colours at the top), or Plain colour. "Repeats every … m" sets how big the texture is (empty = its usual size). Original texture puts the model's own look back. You see it at once; after a few seconds the server puts it on the real map (the real look updates), and every bake and build keeps it. Rows with a texture show "texture: …" in the list.
4. Press Done (or Esc). When you have fixed what looked wrong, press Bake preview to check.

The list has one row per kind of object (all "Crate" objects are one row). Click a row to see its objects light up in 3D; click an object in 3D to find its row. Change the tag in the row's menu - it is saved at once.

Buttons on the 3D view: Colour by tag / Real look (the real textures; a map built before this version shows them after its next Bake preview), Walkable floor (green), Problems (red pins), Whole map. Walk inside puts you in the map at hero height to look around: W A S D move, mouse look (click the view first), Shift run, Space jump, F fly through everything (Space / C up and down), Esc pause, Esc again to leave. Floors, ramps and stairs carry you, walls stop you, decoration does not. It is only a preview - the bake checks what a hero can really reach. Mouse: drag = turn, right-drag = move, wheel = zoom.

Bake preview - let the server check your tags

Press Bake preview (server) after changing tags (about 15 seconds). The green layer shows where heroes can walk. Red pins show problems; the filter Problems lists the rows that have them.

Undo my changes (auto-tags) puts every row back to the tag the auto-tagger chose.

Step 3 · Markers

Markers tell the game where things happen. Pick one on the left, then click on the floor. Click a marker (in 3D or in the list) and a bar appears over the 3D view: ↺ / ↻ turn it 45°, N E S W face it straight to a side, or type the degrees (0 north, 90 east, 180 south, 270 west); ✕ Delete removes it. The arrow in 3D shows where it faces; the list says it in words ("faces south-east"). Each row of the list has the same buttons. Keys: R turn, Del delete, Esc done. Markers with 🔒 come from the model itself and cannot be changed here.

A map can be played as Dungeons only when it has a party start and at least one portal. Without team / flag / item markers those modes still work - the game picks safe spots by itself. Put markers on open floor, not inside walls. The Map status panel on the right tells you what is ready.

Step 4 · Bake & package

Press Bake & package on the server. The server applies your tags and markers, bakes the walkable floor and the walls, runs every check, and builds the downloadable files for Windows and Linux. It takes 30-60 seconds.

The result is 6 files: the map description (_map.json), the walkable floor (_navmesh.bin), the walls (_occ_solid.bin, _occ_fence.bin) and the scene players download (_scene_win64.bundle, _scene_linux64.bundle). Download package (.zip) gives you all six.

Review & publish

As a map maker

When the package is built, press Submit for review (add a note if you like). The owner looks at it and either publishes it or sends it back with a note - you see the note in step 4. Fix, build again, Submit again.

As the owner

1. Switch to Owner (top right; type the owner key if one is set). Maps waiting for review come first in "Your maps".
2. Open the map. Look at it in 3D, at the red pins (step 2) and at the markers (step 3).
3. Step 4 shows the maker's note and a short check list. Choose where to publish (Publish to) and the Folder.
4. Test the target checks the folder can be written. What is already there? warns when a map with the same id would be replaced.
5. Approve & publish copies the 6 files. Or write a note and press Send back.

The History card shows who did what and when.

Publishing to the game VPS

The game VPS serves downloadable maps from /opt/sogacity/maps. New matches and players pick a new map up by themselves - no server restart. Add a target in appsettings.Local.json:

{ "Name": "Game VPS", "Type": "ssh", "Host": "[email protected]", "Port": 22,
  "KeyFile": "C:/Users/you/.ssh/id_ed25519", "Folder": "/opt/sogacity/maps",
  "After": "sudo chown sogacity:sogacity {folder}/*" }

• It logs in with an SSH key only - never a password. Test it once by hand: ssh -i <key> [email protected].
• After runs once the files are copied. For sudo chown without a password prompt, allow just that command for this user on the VPS (sudo visudo), or log in as the sogacity user and leave After empty.
• The folder must be a plain path (letters, digits, / . _ -).

Play your map

Publish to This PC - game map cache, then in the Unity Editor (game project) press Play and open the map list. Without a lobby connection the Editor uses the maps in that cache, so your map is there. (With a lobby, the game downloads exactly what the VPS offers - publish to the VPS for that.)

Try it in the modes it is made for: Dungeons (party start + portals), Capture the Flag / Territory (team starts, flag spots).

When something goes wrong

Where things are

Words