What is Napkin?

Napkin allows you to create and edit application content, associated with a specific NAP project. NAP's main storage format is JSON, which we consider to be quite a readable format. But as projects get larger, it helps to have a more ergonomical view on the data you are creating. Napkin helps you do that. Fire up the editor, launch your NAP application and edit your file to see the changes you make reflected in real time. Files work cross platform and can be shared between Windows, macOS and Linux.

Terminology

The following jargon will be used in this document:

File > New A menu item called New in the menu File in the menu bar at the top of the window or your screen
LMB Click left mouse button
RMB Click right mouse button
CTRL + X Press the X key while holding CTRL (on Windows) or CMD (the curly symbol on Mac)

Launching Napkin

After downloading and extracting the NAP package, you can find Napkin inside the tools/napkin directory. When building Napkin from source it will be placed in the binary output directory, inside a folder called napkin. Napkin is also included with packaged projects. This allows others to edit application content after compilation.

See Project Management for further details, including how to disable including Napkin in packaged projects.

General Structure

Content and configuration settings are stored in .json files. Both can be created and edited using Napkin. The app and Napkin share the same code base. If you adjust and recompile a Resource or Component, Napkin will reflect those changes in the editor.

Opening a Project

To open a project:

File > Open Project

Use the file browser to select the project you want to load. The project is a .json file with the name: project.json. The project.json file points to a Data and ServiceConfig file. Both documents can be edited by napkin. The Data file contains application content, the ServiceConfig file contains application configuration settings.

Before Napkin can load the Data file it will attempt to load all the RequiredModules. Every module has it's own set of dependencies, which will be resolved as well. If loading succeeds, Napkin can safely create and edit files because it can access all the resources exposed by the modules. You can safely launch multiple instances of Napkin to work on multiple projects at once.

Document Management

To make a new data file:

File > New or CTRL + N creates an empty document.

To open a different data file:

File > Open or CTRL + O

To save the data file:

File > Save or CTRL + S

To save the data file under a different name:

File > Save as...

To reload the data file:

File > Reload

To set the data file as project default:

File > Set as project default

Configuration Management

To make a new config file:

Configuration > New creates an empty document.

To open a different config file:

Configuration > Open

To save the config file:

Configuration > Save

To save the config file under a different name:

Configuration > Save as...

To set the config file as project default:

Configuration > Set as project default

Resource Management

Every document contains Resources and Entities.

A resource is a stand alone building block that is always created and initialized on startup of your application. An entity is a special type of resource, which isn't created by default. Only entities that are part of your Scene are instantiated. You can add the same entity to the same scene multiple times, each with different settings.

Create Resource

In the Resources panel, RMB on Resources and choose Create Resource....
Select a resource from the list of available resources.
Double LMB on the newly created resource to change it's name.
Select the newly created resource to edit it's properties.

Edit Resource

Select a resource in the Resources panel.
Edit it's properties in the Inspector panel.

Create Group

In the Resources panel, RMB on Resources and choose Create Group....
Select a group type from the list of available groups.
Double LMB on the newly created group to change it's name.
RMB on the group to add new or existing resources.
RMB on the group and select Create Group to create a sub group.

Create Entity

In the Resources panel, RMB on Entities and choose Create Entity.
Double LMB on the newly created entity to change it's name.
You can delete the Entity by using RMB and choosing Delete.

Add Component to Entity

RMB on your entity and choose Add Component.
Pick the component from the list of available components.
Which Component types are exposed depends on which modules are loaded.

Add Entity to Scene

In the resources Panel: Ensure there is at least 1 scene available.
- Otherwise create one.
In the Scene panel: RMB on a scene and choose Add Entity....
Pick an entity from the list of available entities.

Delete Entity from Scene

In the Scene panel: RMB on an entity and select Delete Instance.

Override Instance Property

In the Scene panel: Select the Component.
Edit the properties of the selected Component in the Inspector panel.

Remove Instance Property Override

In the Scene panel: Select the Component.
In the Inspector panel: RMB on the propery to clear.
Select Remove override

Panels

Napkin consists of several dockable panels that you can arrange yourself.
All panels showing lists of items that can be filtered by name, type or value from the textinput at the top.

Resources

Shows all the resources and entities that are part of your application. Select a resource or component of an entity to edit their default properties. Every resource (under the Resources item) is created when the document is loaded. Entities (under the Entities item) are not created by default. Only entities that have been added to the scene will be instantiated.

Scene

Shows the entities that will be instantiated when the document is loaded. You can add the same entity to the same scene multiple times and override properties on a per instance basis. Components that are marked with a different color have property overrides applied to them.

Note that an empty (new) file does not contain a Scene resource by default, you must explicitly create one. The new scene is available directly after creation.

Configuration

Shows all the service configurations. You can edit a configuration in the Inspector

AppRunner

Allows you to start / stop the application you are working on.

Click on the ... button to browse to the executable.

If your application logs object names in the proper format, you can double-click log messages with that link in the log panel and it will highlight the appropriate object/property in the editor.

Curve

The Curve panel allows for visual editing of a function curve.

Select a FloatFCurve resource in the resource panel.
Open the Curve panel and start editing.

Controls:

LMB on curve points or tangent handles to select them
SHIFT + LMB on curve points to add them to the selection
CTRL + LMB add a point on the curve at the clicked location
LMB + drag in the background to rubberband select point handles or tangent handles
ALT + MMB pan the view
ALT + RMB zoom the view horizontally
SHIFT + RMB zoom the view vertically
SHIFT + ALT + RMB zoom the view both vertically and horizontally
F to frame the selected handles inside the view (if no handles are selected, frame all)
A to frame the entire curve inside the view
Use the buttons in the toolbar or RMB in the curve view to change the interpolation of segments.
Tangent handles can be "broken" for discontinuous curves or "aligned" for c2 continuous curves.

Because of the one-dimensional evaluation nature of function curves, the editor will keep you from creating curves with "overhang" (ie. curves that have multiple solutions). In order to do so, the effective distance of the tangent handles will be limited.

Inspector

This panel shows the properties for the currently selected object.

If an object is selected in the Resources panel you are editing the default (shared) properties
If an object is selected in the Scene panel you are editing unique instance properties
If an object is selected in the Configuration panel you are editing service configuration properties

Most properties are changed by typing in a new value in the value column. Some values like Pointers provide a button next to the field that allows you to select the target object. File properties have their own button that shows a file selection dialog in which you can select the file.

Log

Shows Napkin related messages. If you're running your application from Napkin the output will be shown in this window too.

Each message has a Log Level attached that will indicate its severity:

fine and debug messages are usually not that interesting and will not be shown by default, they're mostly for figuring out the more specific details of your application and the editor.
info messages communicate a notable state change in the editor or your application.
warning indicates you should probably look what is being said.
fatal means something is not right and are very useful for discovering why something doesn't work.

Use the filter to find specific messages. The dropdown on the top-right of this panel allows you to show or hide messages based on their level, in order of importance. warning is more important than debug. If a message pops up that has been underlined, you can double RMB it to reveal the object or property that message is saying something about.

Instance Properties

Shows all component instance property overrides.

Napkin allows you to edit resource properties and instance properties. Instance properties are unique per instance where resource properties are shared by all instances. Only properties of a component can be overridden per instance because a component is instantiated, together with the entity the component belongs to. Select a resource in the resource panel to edit shared properties. Select a component in the scene panel to edit unique properties.

Modules

Shows all currently loaded modules by Napkin. The modules expose all available components and resources to Napkin and the running application.