# IDE Extension

IDE features, like syntax highlighting, error checking, auto-completion and interactive documentation could significantly increase productivity when writing naninovel scripts. We've made an extension for a free and open-source Visual Studio Code (available for Windows, MacOS and Linux) IDE, which provides the essential IDE support for NaniScript syntax.

# Installation

  1. Open extensions window in VS Code via View -> Extensions menu
  2. Search for "Naninovel" and click "Install" button
  3. When a .nani file is opened, the extension will activate automatically

NOTICE

The IDE extension requires .NET Core 3.1 runtime in order to work correctly. VS Code will attempt to install it automatically when activating the extension; in case it fails, install the runtime manually via dotnet.microsoft.com/download.

# Spell Check

To enable spell checking in the naninovel scripts, install a spell checker extension, eg. Code Spell Check and turn on the checking for naniscript language; see the settings section below for an example on how to enable naniscript language for the Code Spell Check extension.

# VS Code Settings

Below is the recommended settings for VS Code to ignore Unity's autogenerated meta files, enable semantic syntax highlighting, word wrap and spell checking (given spell check extension is installed) and disable word-based suggestions (so that they don't constantly popup when you type generic text lines):

{
    "files.exclude": {
        "*.meta": true
    },
    "editor.wordWrap": "on",
    "editor.wordBasedSuggestions": false,
    "editor.semanticTokenColorCustomizations": {
        "enabled": true,
        "rules": {
            "CommentLine": { "foreground":"#5d6470", "italic": true },
            "LabelLine": "#9bc37c",
            "GenericTextLine": "#acb2be",
            "CommandLine": "#6cb2ed", 
            "CommandBody": "#6cb2ed",
            "CommandParameter": "#cd9769", 
            "ParameterValue": "#e2be7f",
            "InlinedCommand": "#6cb2ed", 
            "ScriptExpression": "#62b8c1",
            "GenericTextPrefix": "#e2be7f",
            "InvalidSymbol": "#d14e4e"
        }
    },
    "cSpell.enableFiletypes": [
        "naniscript"
    ]
} 

You can access the settings JSON file via File -> Preference -> Settings menu and clicking "Open Settings (JSON)" button in the upper-right corner of the window. Select "User" tab to edit settings for all projects or "Workspace" to affect only the current project with the naninovel scripts.

Feel free to customize the settings as you see fit.

# IDE Metadata

The project metadata (actors, scripts, custom commands, etc) is stored as NaninovelData/Metadata.xml file. It's automatically generated when Unity editor is started. To update the metadata while the project is opened, either use Naninovel -> Update Metadata editor menu or Ctrl + Shift + U hotkey.

The metadata is automatically synced with the IDE each time it's updated. In case you wish to manually provide a specific project metadata to the IDE extension, you can copy-paste the xml file to ~/.vscode/extensions/naninovel/server folder (where ~ is the user directory).

To disable automatic metadata sync in the IDE and other related features, use extension settings under "Naninovel" category. Restart the IDE after changing the settings (or press Ctrl+Shift+P and select "Developer: Reload Window") for changes to take effect.

NOTICE

When typing generic text lines, author ID auto-completion won't trigger automatically, as it's impossible to guess whether you want to specify author ID or just typing text to print. Use the hotkey (Ctrl+Space by default) to trigger auto-complete manually.

# Video Tutorial

Below is a video tutorial on how to install, configure and use the VS Code extension.

# IDE Attributes

Naninovel has a number of C# attributes to provide various IDE-related functionality to custom commands. For example, to add on-hover documentation to the custom commands and/or parameters, apply Documentation attribute to command type and parameter fields respectively:

[Documentation("Summary of the custom command.")]
public class CustomCommand : Command
{
    [Documentation("Summary of the custom parameter.")]
    public StringParameter CustomParameter;
}

To make a parameter auto-complete with both built-in and custom expression functions and pre-defined custom variables use ExpressionContext attribute.

[ExpressionContext]
public StringParameter Expression;

To auto-complete with values from an arbitrary enumeration type use ConstantContext attribute.

[ConstantContext(typeof(PlatformID))]
public StringParameter Platform;

To auto-complete with a resource use ResourceContext and provide path prefix of the resources. Below example will complete with audio resources:

[ResourceContext(AudioConfiguration.DefaultAudioPathPrefix)]
public StringParameter Audio;

To auto-complete with an actor ID (of any type) use ActorContext attribute.

[ActorContext]
public StringParameter ActorId;

To auto-complete with an actor ID of specific type use ActorContext attribute with first argument specifying path prefix of the actor resources. Below will complete with printer IDs:

[ActorContext(TextPrintersConfiguration.DefaultPathPrefix)]
public StringParameter PrinterId;

To auto-complete appearances of an actor with ID specified in the same named or another parameter in the current command, use AppearanceContext attribute. Be aware, that this requires ActorContext attribute specified in the same command.

[ActorContext(CharactersConfiguration.DefaultPathPrefix)]
public StringParameter CharacterId;
[AppearanceContext]
public StringParameter CharacterAppearance;

Notice, that each of the above attributes allows providing an optional namedIndex argument. Use it with named parameters to specify for which part of the parameter value the attribute belongs. Below example will allow auto-completing name part of the named parameter with character IDs and value part with appearances for the currently typed character (similar to nameless parameter of @char command).

[ActorContext(CharactersConfiguration.DefaultPathPrefix, 0), AppearanceContext(1)]
public NamedStringParameter IdAndAppearance;
Last Updated: November 16, 2021