Documented custom CPACKs

The basic steps in creating a custom unit needs the following:

1. A Model (the thing you see on the map). ¹⁾
2. A Script (You don't see this, but it makes the model do certain things)
3. Documentation. Players enjoy playing more if they understand the capabilities of custom units on the map, regardless of whether they are friendly or enemy units. It is easier for other map makers to implement your units if there is some documentation or guidance on capabilities, limitations and customization options.

The first two things are packaged in a CPACK. Each CPACK can have one or more units and scripts. Note that each model can also have multiple sub-units. A model also needs a “mesh”, a texture or some color.

Documentation is provided via the wiki.

Players enjoy playing more if they understand the capabilities of custom units on the map, regardless of whether they are friendly or enemy units. It is easier for other map makers to implement your units if there is some documentation or guidance on capabilities, limitations and customization options.

An extensive Help system has been built into the game so that custom units (CMOD) and their container (CPACK) can be documented in the wiki that is accessible from inside the game. This allows for an explanation of how to use the unit both for the map maker and for the players.

Anyone could use Blender or any 3D modeler, but many of these have a really steep learning curve.

Following is a list of some free and perhaps easier tools to use.

3D Builder is about as simple as it gets, can load some geometry and simplify it.

https://apps.microsoft.com/store/detail/3d-builder/9WZDNCRFJ3T6

Tinkercad is a good way to make units. Runs in a browser, is free, and takes moment to figure out.

https://www.tinkercad.com/

MagicaVoxel is easy to start with.

• It's free, and doesn't take a lot of training to get going. You can watch a 5 minute video and get the gist of it. Avoid using version 0.99.3, as it has an export bug that will rotate the object and mess with the origin.

• When you export, export as an “obj”. CW4 will want that obj as well as the png file that goes with it. The .obj file is a text file that specifies the geometry of the model and the .png is the texture to place over that geometry.

• .vox files created by MagicaVoxel can be directly imported an in many instances result in a much smaller model with fewer vertexes - this is good for performance. The .vox file that can be imported is the exported version, not the save. It is confusing that Magica Voxel does not differentiate between the two .vox file types

Another good voxel tool is Qubicle.

The full version isn't free. It was used for the prototype units in CW4.

A paid tool that is fully supported in the game (some units have been made with this tool) is AssetForge, a 3D modeling studio with pre-built “blocks” that can be assembled and exported.

Models exported from many external tools (Magica Voxel, Blender, etc.) can usually be imported into the game editor. The guiding principle here is that units should be simple²⁾ - Animation and many of the more advanced features are not suported. Since the game utilizes a 3rd-party package (TriLib)³⁾, for format import/conversions, if one format doesn't work, then attempt either a different format or simplify the model.

The following website may be useful in converting one type of exported model into a different format.

The Open-Asset-Importer-Lib

The game needs both the .obj for the actual model and the texture file (usually a .png file, so make sure you have both available for import into the C-Pack editor.

The CPACK editor can also directly import the .vox files created by MagicaVoxel and this usually results in a more efficient model. If you import the .vox file, the model and texture will both be imported into the CPACK editor.

From a Discord conversation where @knucracker provided some insight into the import process (for a model exported from Blender)

Things like submeshes aren't supported. So depending on how the original model is structured, some meshes might not get loaded. The game basically expects 1 or more top level meshes in a model. It will load them and give them names and create mesh objects in the cpack when imported. It will also attempt to load or extract any textures. For obj files the textures sit along side the model and there may be an a .mtl file that defines the materials. If those are present the game will load them up and import the texture automatically. If not, you can still create a texture in the cpack manually by loading the texture yourself. In either case once you create a cmod and add a mesh to an object, you still need to associate the texture with the mesh in the cmod editor. If you don't then the model will have either just a 'white' untextured look, or it will use vertex colors (if the model was exported with vertex colors). There is also a “vertex color from materials” checkbox in the cpack editor when importing a mesh. That will attempt to create vertex colors based on any materials defined in the model (or in a separate .mtl file). Unfortunately, there are about a million combinations of things. Many dozens of different model formats and many options within any given format, and then options at import time.

For your green vs black edges, I would guess that the texture associated with the mesh is 'wrong' (different), or if vertex coloring is being used that is somehow off (depending on if you had that checkbox selected at import time or not).

The game uses a 3rd party model import package that attempts to create an object hierarchy from what is in the model file. The game then tries to extract meshes from that object hierarchy. There are a million different combinations for how modeling software will organize the meshes. It depends on the modeling software, the export options, and the format being exported to. I don't understand it all either Most of the time I try to stick to single meshes that are relatively simple in nature. I then export and uncheck any fancy stuff in the export (animations, lights, etc. don't need to be exported).

Please don't use images that you do not have the rights to use, that are the property of others, have licensing fees or require attributions. Links to repositories that are not family-safe are not welcome. The sole right of decision-making rests with Knuckle Cracker.

Note: Some of these sites require registration.

• Some links from the MagicaVoxel website
  • ephtracy Githib repo of some MagicaVoxel images
  • Mikelovesrobots/mmmm A city-themed collection of over 400 blocky models you can remix or use outright in your own works.
  • kluchek/vox-models
• Sketchfab . Some models are free, some have rights and others need to be purchased.
• Free3D . Some models are free, some have rights and there are premium models that need to be purchased.
• TurboSquid Ditto.
• Royalty-free images:
  • Google image search -> Tools -> Usage Rights -> Labeled for reuse

Anything you upload to knucklecracker.com website or the affiliated game servers transfers a royalty-free license to knuckle Cracker LLC. for future use in any form. You retain the copyright information, but for uses on Knuckle Cracker and on other platforms associated with Knuckle Cracker games, the license enables us to use the model and to transfer that license to other users for similar purposes. This may include monetization on 3rd party platforms.

Whatever the ownership rights are, it should be indicated in the relevant section of the CPACK.

Units or models that you use in your map may be one of:

• original content - covered by the statement above
• licensed work - this is something that you purchased and obtained usage rights for. If this is not royalty-free, you cannot use it in a map you upload to the knuckle Cracker servers. If it is royalty-free, then you may upload any number of maps using it. However, the right to use the model does not transfer to other mapmakers.
• Attribution-required licensing - you and other players may use the models in maps, In all cases the original attribution should be propagated in the CPACK.
• other - if no attribution is required, no restrictions to use and re-use applies.

Violation of these rules may result in a copyright strike against the Knuckle Cracker website and your content will be removed if found to be in violation.

Mapping from MagicaVoxel (MV) voxels to in-unit size.

Each in-game grid-unit (GU) or cell (sometimes used in CRPL or in game terminology) is 10 MV voxels by default.

The size of a cannon in the game is 3x3x3. So this will need 30x30x30 MV voxels.

MV limits the size of a model to 126 voxels in any direction. In MV, you can't thus build a unit larger than 12.6 cells in either unit.

For units to align perfectly, their size in the X and Z directions should be an odd number of cells.