TutorialSimplePlugin

Create Your First Paracraft Plugin

Here is a video tutorial. video

• Get or clone ParacraftSDK from git to your local disk. It is recommended that you fork the SDK project and stay in sync with us.
• Before you start, make sure you have run Paracraft.exe in ./redist folder to obtain a copy of Paracraft. You can also copy any paracraft installation to the ./redist folder manually.
• Run ./bin/CreateParacraftMod.bat and enter the name of your plugin, such as HelloWorld. A folder at ./_mod/HelloWorld will be generated.
• Run ./_mod/HelloWorld/Run.bat to test your plugin with your copy of paracraft in the ./redist folder.

Basics of Paracraft plugins

There are a few things you need to know about the plugin you just created.

Command line and runtime environment

If you open Run.bat with a text editor, you will see following lines.

@echo off 
pushd "%~dp0../../redist/" 
call "ParaEngineClient.exe" dev="%~dp0" mod="HelloWorld" isDevEnv="true"  
popd 

It specifies following things:

• the application is started via ParaEngineClient.exe in ./redist folder
• the dev parameter specifies the development directory (which is the plugin directory ./_mod/HelloWorld/), which I will explain later.
• the mod and isDevEnv parameters simply tells paracraft to load the given plugin from the development directory, so that you do not have to load it manually.

It is useful to examine ./redist/log.txt file to see if everything goes well. The first few lines of the log file shows the current runtime environment.

Understanding File Path

When programming with NPL, the code will reference other script or asset file by relative file name. The search order of a file is as follows:

• check if file exists in the current development directory (in release time, this is the same as the working directory)
• check if file exists in the search paths (by default it is the current working directory)
• check if file exists in any loaded archive files (mainXXX.PKG or world/plugins ZIP files) in their loading order.
• if the file is NPL script file, look for precompiled binary file at ./bin/filename.o also in above places and order.
• if the file is listed in asset_manifest.txt, we will download it or open it from ./temp/cache if already downloaded.
• if none of above places are found, we will report file not found. Please also note, some API allows you to use specify search order, temporarily disable some places, or include certain directory like the current writable directory. Please refer to the usage of each API for details.

Paracraft Packages

When develop complex plugins, one may need to read and modify the source code of Paracraft. This can be done by installing paracraft package.

In your mod's developmenet directory, one can install source code packages. Just create ./npl_packages folder in your mod directory, and follow the NPL package guide.

Two important packages for paracraft developement is at:

• main package: NPL standard library source code
• paracraft package: paracraft source code

More information about source code overview.

cd npl_packages
git clone https://github.com/NPLPackages/main.git
git clone https://github.com/NPLPackages/paracraft.git

it is NOT advised to modify or add files in the ./npl_packages folder, instead create a similar directory structure in your mod directory if you want to add or modify package source code. If you do want to contribute to our official packages, please fork them on github and send us pull requests. The author of paracraft may consider merging your code in the next public release.

Understanding Plugin Code

When paracraft starts, it will load the file at ./Mod/_plugin_name_/main.lua for each enabled plugin. It is the entry point of any plugin, everything else is up to the developer.

In our example, open the entry file ./_mod/HelloWorld/Mod/HelloWorld/main.lua (see below). Because development directory is set to _mod/HelloWorld by startup command line, the relative path of above file is ./Mod/HelloWorld/main.lua. This is why Paracraft can find the entry file.

local HelloWorld = commonlib.inherit(commonlib.gettable("Mod.ModBase"),commonlib.gettable("Mod.HelloWorld"));

function HelloWorld:ctor()
end

-- virtual function get mod name
function HelloWorld:GetName()
	return "HelloWorld"
end

-- virtual function get mod description 
function HelloWorld:GetDesc()
	return "HelloWorld is a plugin in paracraft"
end

function HelloWorld:init()
	LOG.std(nil, "info", "HelloWorld", "plugin initialized");
end

function HelloWorld:OnLogin()
end

-- called when a new world is loaded. 
function HelloWorld:OnWorldLoad()
end

-- called when a world is unloaded. 
function HelloWorld:OnLeaveWorld()
end

function HelloWorld:OnDestroy()
end

Most plugin will register a class in the "Mod" table, like above. The class usually inherits from Mod.ModBase. The class will be instantiated when paracraft starts, and its virtual functions are called at appropriate time.

For example, if your plugin contains custom commands or block items, you can register them in the init() method.

How to write plugin

There are three recommended ways to extend paracraft

• create your own command: command is a powerful way to interact with the user. The rule of thumb is that before you have any GUI dialog, consider writing a command first. Command is easy to test, integrate, and capable of interacting with other commands. Graphic User Interface(GUI) is good, however, it can only interact with humans in strict ways, commands can interact with both human and other commands or programs.
• create custom items: custom items include entities, items, or blocks. This ensures that your code is modular and independent. The best way to add new functions to paracraft is by adding new block or item types. Consider the color block and movie block in paracraft, which contains both GUI and complex logics.
• add filters: filters is a useful way to inject your code at predefined integration points in Paracraft.

The least recommended way to extend paracraft is to clone the source code files of paracraft to development directory and modify them. Because plugin directory is searched before the main paracraft source code pkg file, it is possible to overwrite source code of paracraft in this way, but you are highly decouraged to do so. If you are requesting a feature that can not be added via the recommended ways, please inform the developers of paracraft to add a new filter for you, instead of modifying our source code directly in your plugin.

Documentation

The best documentation is the source code of paracraft which is in the paracraft package and several plugin demos in the ./_mod folder. Since code is fully documented, use search by text in source code for documentations, as if you are googling on the web.

Debugging

For detailed information, please see NPL Debugging and Logs

• Use ./redist/log.txt to print and check log file.
• press F12 to bring up the buildin debugger.
• use Ctrl+F3 to use the MCML browser for building GUI pages.
• use GUI debuggers for NPL in visual studio.

Plugin Deployment

To deploy and test your plugin in production environment, you need to package all the files in your plugin's development directory (i.e. _mod/HelloWorld/*.*) into a zip file called HelloWorld.zip, and place the zip file to './redist/Mod/HelloWorld.zip'. It is important that the file path in the zip file resembles the relative path to the development directory (i.e. Mod/HelloWorld/main.lua in the HelloWorld.zip).

Once you have deployed your plugin, you can start paracraft normally, such as running ./redist/Paracraft.exe, enable your plugin in Paracraft and test it.

You can redistribute your plugins in any way you like. We highly recommend that you code and release on github and inform us (via email or pull request) if you have just released some cool plugin. We are very likely to fork your code and review it.

Further Readings

• Check out all sample plugins in ./_mod folder.
• Check out all the SDK video tutorials by the author of Paracraft on the website.
• Read NPL Runtime's official wiki