This script is a .vpp file loader for using 3d voxel models created with
Voxel Paint in your three.js projects. This loader is used by projects such as
My Empire and
My Colony 2. The loader takes your vpp file and converts it into a
mesh object that you can add to a threejs scene. In some instances if special features are used in your model, it may return a
Group object instead of a single mesh. You can learn more about how to use threejs here:
https://threejs.org/
You can download the javascript file below, and this thread will be kept up to date with the latest release of the loader.
Last Updated: 12/22/2020
Basic Usage Instructions:
In your HTML:
<script src="vpploader.js"></script>
In your Javascript, .vpp models can be loaded from either a URL or from a Javascript Object. Here are examples for both:
let filename = "mymodel.vpp";
let color = null;
let ratio = 16;
let opacity = 1;
// load from URL
let mesh = vppLoader.getMeshFromVPP(filename,color,ratio,opacity);
scene.add(mesh);
// load from object
let vppObject = JSON.parse(vppString);
let mesh = vppLoader.getMeshFromVPPObj(vppObject,color,ratio,opacity);
scene.add(mesh);
Besides filename, all parameters are optional.
filename is (of course) the url to your .vpp model.
If the
color parameter is selected, all voxels that are fuscia in color (
#ff00ff) will be converted to the specified color. Must be a hex color. If this is not specified or set to null, fuscia voxels will just be rendered as normal.
The
ratio parameter will automatically scale your .vpp model to fit your scene. For example, the ratio above is set to 16. This means that 16 voxels in your .vpp object will be equal to a width of 1 on the model you add to your scene. This is an optional parameter and you can also just handle scaling on your own.
Setting the
opacity parameter will set the opacity of your object. Must be between 0.0 and 1.0.
The vpploader script will automatically take care of reusing geometries for you when appropriate, in the event that you are adding multiple instances of the same object to your project.
If you have any questions or suggestions for the loader, feel free to leave them in this thread! I will be adding features and improvements as I add them to the .vpp file format, so if you are using this script, make sure you check back to ensure that you have the latest version of the loader.