IDE Setup and Compile Checking

Why scripts need a companion project#

Server scripts and modules are loose .cs files under server/scripts/ and server/modules/. The game server compiles each one itself at startup, prepending a hidden block of using directives so ScriptPlayer, ModuleLoader and TaskScript resolve without you writing anything. That is convenient in the Script Editor, which knows about the prelude and offers autocomplete from the generated API database, but a general-purpose C# editor opening one of those files sees an unresolvable soup: no completion, no go-to-definition, and no error until the game boots and the server log reports a compile failure.

The IDE companion project fixes that. generate_script_project writes a real .csproj plus a global-usings file into the project's server/ folder, so any C# IDE resolves engine types and your own module types while you edit. Building that project is also a genuine pre-flight check: script mistakes become build errors at your desk instead of log lines after launch.

Two facts to keep in mind:

• The running server never reads these files. They exist only for your IDE. The server keeps compiling scripts/** and modules/** on its own at runtime.
• They are never shipped. Push to Test and Publish zip only server/data, server/modules, server/scripts and server/schemas. The Script Editor's file tree also hides them (.g.cs, .csproj, .props, .targets, .sln files and the obj/bin folders), so they never show up as game content.

What gets written#

The project sets Nullable to annotations (so T? works without warnings), disables implicit usings (the prelude file replaces them), and silences warnings that are noise for script fragments: CS0168, CS0169, CS0414, CS1591, CS8019, CS8632.

Prerequisites#

1. The .NET 8 SDK. The editor's own Dev Test needs it too; if dotnet --version does not print a version, install it from dot.net.

2. The engine assembly, RealmServer.dll. The csproj probes these locations in order and uses the first that exists:

   • server/builtin-assemblies/RealmServer.dll inside your project;
   • %USERPROFILE%\Documents\GitHub\Vastopia-Server\Server\bin\Debug\net8.0\RealmServer.dll;
   • ..\..\..\GitHub\Vastopia-Server\Server\bin\Debug\net8.0\RealmServer.dll relative to server/.

   If none exists, the build prints the warning Vastopia engine assembly not found - IntelliSense cannot resolve engine types and every engine type shows as unresolved. Either pass the path explicitly (dotnet build -p:VastopiaServerDll=C:\path\to\RealmServer.dll), or drop a copy of the DLL into server/builtin-assemblies/.

If you have the server source checkout linked in Settings > Editor > Source Checkouts > Server project (the folder holding RealmServer.csproj), the simplest way to produce the DLL is to press Dev Test once: the editor runs dotnet build on that checkout and the output lands in bin/Debug/net8.0/RealmServer.dll, exactly where the second probe looks.

Generate the project#

generate_script_project is an MCP tool, so you run it from your AI assistant with the project selected (see MCP setup). There is no button for it in the editor.

1. Ask the assistant to run generate_script_project. With no arguments it writes the three files and lets the csproj probe for the engine DLL. The result reports action: "create" the first time and "update" on later runs.
2. To pin the engine assembly, pass server_dll with the full path to RealmServer.dll.
3. To leave noisy files out of the IDE compile, pass exclude with a semicolon-separated list of paths relative to server/, for example modules\Content\Drops\ItemDropModule.cs. The value lands in the csproj's VastopiaExclude property, which you can also edit by hand later.
4. Pass dryRun: true to preview the files without writing them.

Re-run the tool whenever the engine prelude changes (the generated usings file says so in its header); the three files are regenerated in place.

Open the project in your IDE#

Open the server/ folder, or server/VastopiaScripts.csproj directly, in VS Code (with the C# extension), JetBrains Rider or Visual Studio. You get:

• Completion on the script API (player., ScriptWorld., npc.Combat.) and on your own modules, including FishingModule.Instance. for any module declared as ModuleBase<FishingModule>.
• Go-to-definition into the engine assembly's types and into your modules.
• Red squiggles on real errors as you type.

Keep editing files where they already are: the IDE compiles scripts/** and modules/** in place, so there is nothing to copy or sync, and the Script Editor works on the same files. If you save a file from the Script Editor after changing it in your IDE, the editor notices the file was modified on disk and asks before overwriting it (File Changed on Disk, with an Overwrite button).

Compile-check before launch#

Building the companion project compiles every script and module against the real engine assembly:

cd <your-project>/server
dotnet build VastopiaScripts.csproj

A clean build means every file parses and every engine call resolves. Read the output like any C# build: each error line names the file, line and column, the CSxxxx code and the message.

One fidelity gap, on purpose#

The server compiles each script file and each module file separately, in its own assembly. The companion project compiles them all together. The IDE is therefore slightly more permissive than the runtime in two specific ways:

Both are IDE-only artefacts; the runtime behaviour is the one that ships. See Scripting overview for the compile-per-file rule.

What Dev Test checks for you#

You do not have to remember to build before testing. Pressing Dev Test saves the project, then validates every .cs file under server/scripts/ and server/modules/ in two passes before the server starts:

1. Structural lint - instant and dependency-free. Catches mismatched or unclosed ( ) { } [ ], unterminated strings, characters and block comments, and a { opened while an if/while/for/foreach/switch/catch/using/lock condition is still missing its ). If anything is found, the compiler pass is skipped.
2. Compiler pass - runs only when no structural errors were found and the server checkout has been built (bin/Debug/net8.0/RealmServer.dll exists). It builds a throwaway project over all the scripts on a background thread and keeps only parser-level diagnostics (codes CS1000-CS1999, such as ; expected or ) expected). Semantic codes are deliberately dropped here because the editor cannot reproduce the server's exact reference set, so they would be false positives - that is what the companion project is for.

If errors are found, the Script Validation dialog opens instead of the server: a summary line (N errors found in your scripts), a status note, and a tree of problems grouped by file as Line n:m - message [code]. Double-click a problem to jump to that line in the Script Editor. Press Launch Anyway to start the server regardless, or Close to fix things first. When the compiler pass could not run you will see Server not built yet - only structural checks ran. with the tip to run Dev Test once, because that first run builds the server.

Reading server logs#

The server reports compile problems at startup and never crashes on them: a script that fails to compile is logged and skipped, and the rest of the game boots without it. That is why a feature "silently not working" usually means one log line you have not read yet.

The local Dev Test server#

On Windows, Dev Test launches the server in its own Command Prompt window titled EzRealm Server (Play Local), running dotnet RealmServer.dll <port> with the working directory set to your project's server/ folder and DEV_ALL_ADMIN=1 (so built-in admin commands work while testing). Keep that window visible. The lines that matter:

Compiled scripts are cached under server/scripts/.compile_cache/ (override the location with the EZREALM_SCRIPT_CACHE_DIR environment variable). The cache key includes the script's content, so edits always recompile; delete the folder if you want to force a full recompile and see every file's result.

When a script is already running you can also log from it: player.Log("...") writes to the same console tagged with the player's username, and modules have Log, LogWarning and LogError.

Running the server by hand#

To check a project's scripts without the editor or a client, run the engine directly and watch the boot output:

cd <your-project>/server
dotnet "<Vastopia-Server>/Server/bin/Debug/net8.0/RealmServer.dll" 7991

Grep the output for Compilation errors and CS codes. Two lines are harmless noise on a developer machine: Control server failed to start ... Access is denied (the hot-reload HTTP listener needs elevated rights on Windows) and No pre-compiled assemblies dir (platform module binaries only exist in hosted containers). Stop the process when you are done; it runs until killed.

The platform test server#

After Play Local or Push to Test, your game runs on a platform test server, and its console is not on your machine. The Server Logs button at the top right of the editor opens a log view for the game linked to your project:

• Lines picks how many recent lines to fetch: 100, 200, 500 or 1000.
• Refresh fetches now; the view also refreshes on its own every 3 seconds while open.
• Auto-scroll keeps the newest line in view; Clear empties the display.
• Lines containing error, exception or fatal are tinted red, warn yellow, and info, ready or listening blue.

The view reads the test deployment's logs, requires you to be signed in to the editor, and needs the project to be linked to a game (it reports No project open or no game ID configured otherwise). Play Local switches to it automatically once the client is launched. See Test your game for the difference between Dev Test, Play Local and Push to Test.

Troubleshooting#

With AI (MCP)#

generate_script_project creates or refreshes the companion project (server_dll, exclude, dryRun). read_server_logs fetches a deployed game's logs - mode is test (default), live or beta; lines defaults to 200 and is capped at 2000; contains, exclude and min_level (debug, info, warn, error) filter the result, and lines with no level prefix are always kept so legacy output is never hidden. get_script_api returns the API surface so scripts are written against the real engine, and write_server_script generates compile-ready skeletons per script kind. Full list: MCP tools reference.