The NW.js object allows access to features specific to the NW.js exporter Paid plans only, such as reading and writing files to the local disk drive.
Note that the AJAX object can read files from the application folder (but not write files) when exporting to NW.js. Further, the File System object provides ways to access local files and folders from browsers and is also supported in both NW.js and Windows WebView2 exports. This may allow you to implement file operations in a more cross-platform manner.
What is NW.js?
NW.js is essentially a standalone version of the Google Chrome web browser, but while looking like an ordinary desktop app (so there are no browser tabs, address bar, back/forward buttons etc). Exporting using NW.js allows your project to run as a standalone desktop app on Windows, Mac and Linux, and does not require any particular other browser to be installed.
Using file paths correctly
Never hard-code paths (such as using an action to write to a fixed file path like "C:\MyGame\MyFile.txt"). This is unfriendly to users, and is often perceived as unprofessional, untidy, or filling the user's system with junk. Not only that but in many cases it simply will not work, since not all users have permission to read or write to folders outside of their user directory.
It is tempting to solve this by writing files to the application's folder. However this also may not work; on many versions of Windows, the Program Files folder requires administrator permission to write to, although you can read from it.
The solution is to write to the user's folder, which you almost certainly have write permission for. This is provided by the UserFolder expression. The correct way to determine a file path in the user's folder is like this:
NWjs.UserFolder & "myfile.txt"
If you only need to read files, and don't need to write them, you can safely use the application folder (NWjs.AppFolder) instead.
Text file encoding
The NW.js object has the ability to read and write text files on disk. To support all possible languages, it always reads and writes with the UTF-8 encoding. To ensure the plugin reads your own text files correctly, ensure they are encoded as UTF-8.
NW.js conditions
- On folder dialog OK
- On folder dialog cancel
- Triggered after the Show folder dialog action, depending on if the user selected OK or Cancel. The ChosenPath expression contains the selected folder after an OK.
- On open dialog OK
- On open dialog Cancel
- Triggered after the Show open dialog action, depending on if the user selected OK or Cancel. The ChosenPath expression contains the selected file to open after an OK.
- On save dialog OK
- On save dialog Cancel
- Triggered after the Show save dialog action, depending on if the user selected OK or Cancel. The ChosenPath expression contains the selected file to save after an OK.
- On binary file read
- On any binary file read
- Triggered after the Read binary file action when the read completes. The file data is now available in the chosen Binary Data object. The "any" variant triggers regardless of the tag, which can be retrieved with the FileTag expression.
- On binary file written
- On any binary file written
- Triggered after the Write binary file action when the contents of the chosen Binary Data object have been successfully written to the file. The "any" variant triggers regardless of the tag, which can be retrieved with the FileTag expression.
- On file dropped
- Triggered after the user drag-and-drops a file in to the application window. The DroppedFile expression contains the path to the file that was dropped in, allowing you to load it to read its contents.
- On file system error
- Triggered when any file operation fails, such as attempting to write a file in a folder the user does not have permission to access. The FileError expression contains more information about the type of error.
- Path exists
- Test if a given folder or file path exists on the user's system.
NW.js actions
- Show folder dialog
- Open a dialog allowing the user to pick a folder on their local system. If the user selects OK, On folder dialog OK triggers and the ChosenPath expression contains the selected folder.
- Show open dialog
- Open a dialog allowing the user to choose a file to open on their local system. If the user selects OK, On open dialog OK triggers and the ChosenPath expression contains the selected file. The Accept parameter is a comma-separated list of file extensions or MIME types that the dialog can use to filter possible files. For example, ".txt,.json" will allow filtering by all .txt or .json files, and "text/*" will allow filtering by any file with a text MIME type.
- Show save dialog
- Open a dialog allowing the user to choose a file to save to on their local system. If the user selects OK, On save dialog OK triggers and the ChosenPath expression contains the selected file. The Accept parameter is a comma-separated list of file extensions or MIME types that the dialog can use to filter possible files. For example, ".txt,.json" will allow filtering by all .txt or .json files, and "text/*" will allow filtering by any file with a text MIME type.
- Append file
- Add some text to the end of the file. This is usually faster than writing the full file again with some new content at the end. Appending to files can be useful for logging.
- Copy file
- Make an identical binary copy of a file at a new location.
- Create folder
- Create a new folder on the user's local system.
- Delete file
- Delete a file from the user's local system. Be sure to use this carefully, since a mistake could mean deleting the wrong file.
- List files
- Read a list of every subfolder and file in a given folder. After this action the ListCount and ListAt expressions can be used to return the items in the list.
- Move file
- Make an identical binary copy of a file at a new location, then delete the old file. Note you should use the Rename file rather than the Move file action if you intend to move it to a new name in the same folder.
- Open browser
- Open the default browser on the system to a given URL.
- Read binary file
- Read the contents of a file to a Binary Data object. When the read completes, On binary file read triggers. A tag can be used to distinguish multiple parallel reads.
- Rename file
- Set a new name for an existing file path.
- Run file
- Run the file at an existing file path. Typically this is used for executable programs. To open a different kind of file, use the Shell open action.
- Shell open
- Open a file with the system default application. (The name "Shell" means the operating system user interface, which handles the default applications.) For example using Shell open on a .pdf file will open the default PDF viewer on the system to view that file.
- Write binary file
- Write the contents of a Binary Data object to a file. When the write completes, On binary file written triggers. A tag can be used to distinguish multiple parallel writes.
- Write text file
- Write a text file to the user's local system. If the file does not exist, it is created. If the file already exists, its content is overwritten.
- Maximize
- Maximize the window on the user's desktop. It will take up most (but usually not all) of the display.
- Minimize
- Minimize the window to the operating system start bar or dock.
- Request attention
- Perform an operating-specific activity to show attention is required from the user, such as by flashing the title bar of the window.
- Restore
- Restore the window to show it again after minimizing.
- Set always on top
- Set whether the window always appears on top of other windows.
- Set width
- Set height
- Set the dimensions of the window. Note this includes the window title bar and borders, so the actual displayed area of the game may be less than the window size you set.
- Set maximum size
- Set minimum size
- Set the maximum and minimum sizes that the user can resize the window to.
- Set resizable
- Enable or disable resizing of the window.
- Set title
- Set the text that appears in the title bar or caption of the window.
- Set X
- Set Y
- Set the position of the window on the user's desktop, in pixels relative to the top-left of the primary monitor.
- Show dev tools
- Since NW.js is based on Chromium, this action brings up the Chromium developer tools (such as Javascript debugger and console). This may be useful to inspect console messages or for developing plugins with the Javascript SDK.
- Unmaximize
- Undo a window maximize, restoring the window to its previous size.
NW.js expressions
- ArgumentAt(index)
- ArgumentCount
- Retrieve the command-line arguments the application was launched with. The number of arguments is provided, and each can be accessed by its zero-based index.
- ChosenPath
- Return the path that was selected after On folder dialog OK, On open dialog OK or On save dialog OK.
- AppFolder
- AppFolderURL
- Return the path to the application's folder, including the trailing slash. Read permission can be expected, but write permission cannot be guaranteed (for example the Program Files folder on Windows requires administrator permission to write to).
- DroppedFile
- In On file dropped, the path to the file that was dropped in to the application's window.
- FileError
- In On file system error, a string with details about the type of error that occurred.
- FileSize(path)
- Return the size of a given file, in bytes.
- FileTag
- In a trigger like On any binary file read, this returns the tag of the associated action that resulted in the trigger.
- ListAt(index)
- After the List files action, returns the file or folder name at the zero-based index in the list.
- ListCount
- After the List files action, returns the number of files or folders in the list.
- ProjectFilesFolder
- ProjectFilesFolderURL
- Return the path to the folder containing project files, including the trailing slash. This is useful for accessing any additional files imported to the project. Read permission can be expected, but write permission cannot be guaranteed (for example the Program Files folder on Windows requires administrator permission to write to).
- ReadFile(path)
- Open the given file and return its text content as a string. Note that each time this expression is used the file is opened and read from disk. Therefore if the expression is used twice, the file is opened and read twice, which can impact performance. If necessary first read the file to a variable, then reference the variable multiple times.
- UserFolder
- Return the path to the user folder, which is typically where the user's documents and other personal files are kept. Both read and write permissions can be expected.
- WindowWidth
- WindowHeight
- Retrieve the current size of the window in pixels. Note this includes the window title bar and borders, so may be larger than the display area of the game.
- WindowTitle
- Get the current text showing in the window title bar or caption.
- WindowX
- WindowY
- Get the current position of the window in pixels relative to the top-left point of the user's primary monitor.