Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
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
./redistfolder to obtain a copy of Paracraft. You can also copy any paracraft installation to the
./bin/CreateParacraftMod.batand enter the name of your plugin, such as HelloWorld. A folder at
./_mod/HelloWorldwill be generated.
./_mod/HelloWorld/Run.batto test your plugin with your copy of paracraft in the
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
devparameter specifies the development directory (which is the plugin directory ./_mod/HelloWorld/), which I will explain later.
isDevEnvparameters 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/cacheif 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.
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:
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_packagesfolder, 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
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.
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.
For detailed information, please see NPL Debugging and Logs
./redist/log.txtto print and check log file.
F12to bring up the buildin debugger.
Ctrl+F3to use the MCML browser for building GUI pages.
- use GUI debuggers for NPL in visual studio.
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
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.
- Check out all sample plugins in
- Check out all the SDK video tutorials by the author of Paracraft on the website.
- Read NPL Runtime's official wiki