Visual Novel Maker comes with a lot of useful built-in commands to easily create own visual novels. However, in special situations depending on the complexity of the visual novel the built-in commands are maybe not enough or it is necessary to modify them.

 

In this example we want to add a new scene command allowing us to display a card from the"Adding a new database category " example on screen. To do that, lets open the Extension Editor through the menu under View > Extension.

 

Next we will make a right-click on the"Scene Commands " folder and select New > Scene Command to create a new scene command. We will call it "Show Card " since we want to show one of our cards on the screen. It already contains some basic JSON which looks like this:

 

{

    "id": "ext.ShowCard",

    "group": "Custom",

    "defaultValue": {},

    "quickItems": []

}

 

Lets go through the JSON step by step:

 

The unique identifier for the command. It can be any kind of text as long as it is unique. So you don’t need to follow any kind of format or syntax. However, the default syntax is <module>.<name> like commands which are more specific for visual novels using vn.<name> while more general commands are using gs.<name>. However, you shouldn’t use vn.<name> or gs.<name> to avoid confusion since they are only for built-in commands.

 

The group/category where the new command should be added to. You can use any of the already existing categories or just define your own like "My Custom Commands ". In our case we are just using"Custom ".

 

The default values for the command if the command is new created like if the users drags a new command from the toolbox to scene content.

 

Contains a list of items. An item is a UI control which lets the user interact with the command to input number or text values or to select a value from a drop-down menu.

 

For a full list of possible fields for scene commands just take a look at the Plugin API Reference.

 

Before we can design the UI for our command we have think about what exactly the command should do and which data we need for that. In our example we need two things: The card and the position on screen where the card should be displayed. Lets implement the UI for that next:

 

"quickItems": [

    {

        "type": "GSQDataRecordField",

        "attribute": "cardId",

        "dataSource":"cards",

        "label": "Card",

        "valueFormula": "return fmtRecord('cards', p.cardId);",

        "variableButton": { "dataSource": "numbers" }

    },

    {

        "type": "GSQStepper",

        "attribute": "position.x",

        "valueFormula": "return fmtNumVar(p.position.x);",

        "label": "X",

        "variableButton": { "dataSource": "numbers" },

        "minimum": -GS.CONST.MAX_NUMBER_VALUE,

        "maximum": GS.CONST.MAX_NUMBER_VALUE

    },

    {

        "type": "GSQStepper",

        "attribute": "position.y",

        "valueFormula": "return fmtNumVar(p.position.y);",

        "label": "Y",

        "variableButton": { "dataSource": "numbers" },

        "minimum": -GS.CONST.MAX_NUMBER_VALUE,

        "maximum": GS.CONST.MAX_NUMBER_VALUE

    }

]

 

As we can see we added three items to our command. One popup-control to select the card to display and two number fields to select the position. Lets take a deeper look at the fields of each item. Each item can have a few general fields which are available for each type of item but also some type specific fields. Lets start with the general fields used in that example:

 

Indicates the type of the item like if its a popup-field, a number-field, etc. The type must be present.

 

The backend JavaScript attribute name where the item will store its data. You can access the data later via script using that name. The name should be unique for the command to avoid collisions.

 

A JavaScript formula to calculate the displayed text for the control. We are using the fmtXXX functions here which automatically doing the most work for us. Like fmtRecord automatically return the display text for a specified record and fmtNumVar return the display text for a value which can be calculated by variable. For more info check the Plugin API Reference.

 

The label/description of the field displayed to the user.

 

Indicates that the value can be calculated by a variable as well. With "dataSource " you can specify which type of variables should be used. Since all our fields storing number values internally we are using"numbers " for number-variables.

 

Now lets take a look at the type specific fields used in this example:

 

Used in our data-record field to define the data-source to take the data records from. That is the name specified in the data record view’s category/attribute field. So we are using"cards " here to access our cards. Internally our cards are stored as numbers.

 

The minimum value for our number-fields. We are using a global constant GS.CONST.MAX_NUMBER_VALUE here to allow the max negative number value.

 

The maximum value for our number-fields. We are using a global constant GS.CONST.MAX_NUMBER_VALUE here to allow the max number value.

 

Lets click on the"Preview " button next to see an interactive preview of our command to check if the UI looks right.

 

Thats it! We are done on the editor-side! We just need to save our project and restart Visual Novel Maker to see our changes. If we open a scene and go to the command toolbox we can see a new category"Custom " there containing our new command which is ready to use!