nwn-devbase

nwn-devbase is a cli tool for transforming .mod archives to YAML and back, intended to enable Neverwinter Nights (NWN) module developers to version control their module development. The tool supports both vanilla NWN and NWN:EE

In addition, the texts here are meant to function as a reference for users unfamiliar with git and Docker. INTRODUCTION introduces the problem areas git and Docker solve, and attempts to explain the development workflow.

The basis for this work is what I have already done on an existing server; Bastion of Peace.

Why do I need this?

You don't, but it might make version controlling your module development easier and more productive for you. It's not optimal to version control a mod archive directly, nor the gffs it unpacks to, because git considers these file formats as binary. You want to version control text, and this conversion is not straight forward.

Quickstart reference

Initialize new projects by running

mkdir my-project && cd my-project
git init
nwn-build init
cp path-to-my-module.mod server/modules/
nwn-build extract
git add -A && git commit -m "Initial commit"

nwn-build init does the following:

1. .nwnproject is created
2. .nwnproject/.gitignore is created to exclude the cache dir, unless it's already there
3. Prompts to specify the module file name
4. .nwnproject/config.rb.in is created with a configuration that specifies the module filename, unless it's already there
5. Prompts to create the expected directory for the module at ./server/modules/
6. If yes, .gitignore is created to exclude the server dir, unless it's already there

These files are important. Start tracking them with git add -A && git commit "Initial commit"

See nwn-build -h for further usage instructions.

Common dependencies

Note to windows users: chocolatey is a package manager for Windows that empowers you to install and upgrade software from the command line. For those not using chocolatey the direct download links follow after the choco command.

Everyone will need git

• Arch: pacman -S git
• Ubuntu: apt install git
• Windows: choco install git git-scm.com

Install and run

You can run nwn-devbase in the following ways:

1. Natively
2. or in a docker container

To run natively you have to install Ruby, nim, neverwinter_utils.nim, and an nss compiler. To run with docker you only need docker installed.

Docker

nwn-devbase has been containerized with the intention of easing up on the dependencies and configurations required to run natively, by only requiring Docker. The image jakkn/nwn-devbase should be used to spin up short lived containers that run a single command and dies quietly when they're done.

Use the following command to run devbase in a container

docker run --rm -it --user $UID:$UID -v "$(pwd):/home/devbase/build" jakkn/nwn-devbase

It is recommended to alias this command to something like nwn-build. Linux: append to ~/.bashrc

alias nwn-build='docker run --rm -it --user $UID:$UID -v "$(pwd):/home/devbase/build" jakkn/nwn-devbase'

Windows: TODO - Figure out how to store PS functions. Help wanted!

function nwn-build {docker run --rm -it -v \"$(pwd):/home/devbase/build\" jakkn/nwn-devbase}

Limitations:

• The command must be run in the project root, because docker cannot navigate to the parent of the mounted volume in the host directory tree
• Linux host only: The container runs with UID 1000 by default if --user is not specified

Install Docker:

• Arch: pacman -S docker
• Ubuntu: See https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/
• Windows: Depends on Hyper-V support (Windows Pro and above), please refer to https://forums.docker.com/t/linux-container-on-windows-docker-host/25884/2 for details.
  • No Hyper-V: choco install virtualbox docker-toolbox
  • With Hyper-V: choco install docker-for-windows

Update the image by running docker pull jakkn/nwn-devbase

Natively

You will need

• Ruby, to run the build script and nwn-lib to convert gff to yml

  • Arch: pacman -S ruby
  • Ubuntu: apt install ruby
  • Windows: choco install ruby rubyinstaller.org

• nwnsc, the nwscript compiler

  • All platforms: https://neverwintervault.org/project/nwn1/other/tool/nwnsc-nwn-enhanced-edition-script-compiler

• nim, to use neverwinter_utils.nim

  • Arch: pacman -S nim
  • Ubuntu: choosenim
  • Windows: choosenim

• neverwinter_utils.nim for module packing and extracting

  • All platforms: https://github.com/niv/neverwinter_utils.nim

Install nwn-devbase

git clone https://github.com/jakkn/nwn-devbase.git
cd nwn-devbase
gem install bundler
bundle install

If there are errors it is most likely due to improper Ruby configurations or missing PATH entries. See troubleshooting.

Symlinks

Symbolic links are used to make files appear in multiple directories. This is useful for making build.rb available on PATH, and to reveal .mod files to the aurora toolset which is necessary because devbase build the module to PATH_TO_REPO/server/modules/module.mod while the toolset looks for the file in NWN_USERDIR/modules/.

Linux

You may run ruby build.rb install to automatically symlink build.rb to $HOME/bin/nwn-build. If you do this, make sure $HOME/bin is on your PATH, see Paths for details. Alternatively run ln -s "$(pwd)/build.rb" "/usr/local/bin/nwn-build" or modify the destination to your preference.

Make a module accessible to the toolset by running ln -s "PATH_TO_REPO"/server/modules/my-module.mod "NWN_USERDIR"/modules/ Replace NWN_USERDIR with the path to where your local NWN client reads modules from, and PATH_TO_REPO with the path to the repository of a given project.

Windows

Run all shell commands in PowerShell. Alternatively use Link Shell Extension to create symbolic links instead of using the shell.

Use the right click menu from Link Shell Extension, or run cmd /c MKLINK "$env:USERPROFILE\bin\nwn-build.rb" "$(pwd)\build.rb", and make sure $HOME/bin is on your PATH, see Paths for details.

Make a module accessible to the toolset by running cmd /c MKLINK "NWN_USERDIR\modules\my-module.mod" "PATH_TO_REPO\server\modules\my-module.mod" Replace NWN_USERDIR with the path to where your local NWN client reads modules from (mine is ), and PATH_TO_REPO with the path to the repository of a given project.

Paths

Information on what environment variables are can be found by looking at the wikipedia article. Instructions on how to set one can be found using google.

For nss compilation to work, it may be necessary to set some PATHs if the defaults do not match with your system environment. Either specify the paths at run time with

NWN_USERDIR="$HOME/Beamdog Library/00829" NSS_COMPILER="$HOME/bin/nwnsc" nwn-build compile

or set them permanently in system environment variables. Placing the compiler in a folder on PATH, like $HOME/bin should also work.

NSS compiler

build.rb looks for the NSS_COMPILER environment variable, and defaults to nwnsc if that does not exist. Either add the compiler to your PATH, or create the NSS_COMPILER environment variable that points to the nss compiler of your choice.

NWN install dir

The compiler run arguments specify game resources located in NWN_USERDIR environment variable. This is needed to locate nwscript.nss and base game includes.

Use

ruby ./build.rb -h

To version control your changes to the sources use the git commands git pull, git add, git commit, git push accordingly.

Hints

Scripting in other editors

Some might find other editors to be faster, easier to navigate, and to provide better syntax highlighting than the Aurora toolset.

Visual Studio Code

VSCode is an excellent choice for scripting outside of the toolset. The editor will prompt you to add the nwscript extension when you open a .nss file.

Sublime Text

TODO: OUTDATED INSTRUCTIONS Setting up Sublime Text for scripting requires a few steps to set up the custom NWN script compiler (NWNScriptCompiler).

• Install Sublime Text 3
• Install Package Control
• Install STNeverwinterScript plugin
• Open the Sublime project described by the file nwn-devbase.sublime-project located in the root directory of this repository
• Tools->Build System->NWN compile
• Hit ctrl+b to compile open nss files or ctrl+shift+b for all the other build options

Windows PowerShell

Windows users may find this blog post titled make powershell and git suck less on windows useful.

Troubleshooting

"Too many files open": nwn-lib opens all files for reading at the same time when packing the module. This can lead to an error stating too many files are open. Fix:

• Linux ulimit -n 4096 (or any other number higher than the number of files in the module)
• Windows the Java library modpacker is used instead. If modpacker cannot be found build.rb will print out instructions.

I have installed Ruby but it does not work: This is most likely due the Ruby executable missing from your PATH environment variable. If this is new to you and you're on Windows, please ask google first. Linux users should not have this issue.

build.rb illustration

An illustration of how the build script operates is available at https://drive.google.com/file/d/156hELaw_3fwGeCWexYFmJDJiBrJu23-x/view?usp=sharing

Feedback

Feedback is greatly appreciated. If you have any thoughts, suggestions or ideas about how to improve this project, please feel free to raise issues, create pull requests, or look me up on email or on discord.