The NIL file format

The official Novel IL format is defined with this JSON schema, which is used by Novel IL tools to validate codes.

This page contains a human-readable description of the Novel IL format.

Top-level structure

At the highest level, a Novel IL is a dictionary with a few keys:

metadata (dict)
cells (list)

{
  "metadata": {
    "title": "Alice's Wonder Forest",
    "authors": [
      "Alice Project"
    ],
    "languageInfo": [
      "English"
    ],
    "version": "1.0.0"
  },
  "cells": [
    {
      "name": "Alice", // name or character
      "images": {
        "foreground": ["alice-normal.png"],
        "background": ["green-park.png"]
      },
      "text": "Hi, there." // text or message
    },
    {
      "name": "Rabbit", 
      "images": {
        "foreground": ["rabbit-normal.png"],
        "background": ["green-park.png"]
      },
      "text": "Hi, Alice!"
    }
  ]
}

Cell

There are a few basic cell types for encapsulating code and text. All cells have the following basic structure:

{
  "name": "character name",
  "text": "character message", // text or message
  "images": {
    "foreground": ["foreground-image.png"], // e.g. character image
    "background": ["background-image.png"]
  }
}

Cell fields officially defined for Novel IL are listed here:

Key	Value	Interpretation
`name`	`str`	The character name
`text`	`str`	The message box text
`images`	foreground and background `lists` of `strings`	Display images
`audio`	foreground and background `lists` of `strings`	Music, sound effects, etc.
`movies`	foreground and background `lists` of `strings`	Play movies

Metadata

Metadata is a place that you can put arbitrary JSONable information about your NIL, cell, or output.

Metadata fields officially defined for Novel IL are listed here:

Key	Value	Interpretation
`title`	`str`	A game title
`authors`	`list` of `strings`	A list of authors of the novel game
`description`	`str`	A description of the game
`version`	`str`	The version of the novel game file
`license`	`str`	The license of the game
`languageInfo`	`list` of `strings`	The languages the game supports