02. Getting Started
MiEx is written in Java and so requires Java 8 or newer to be installed on your pc. It is recommended to install the latest version of Java, which is typically available as the JDK (Java Development Kit) and can be downloaded from here: https://www.oracle.com/java/technologies/downloads/. If you want to download Java 8 instead, then you can find that here: https://www.java.com/en/download/manual.jsp.
Once installed, you can download the MiEx.jar file from the releases page (found under "Assets" for the release). The MiEx.jar file will by default create some files and folders in the same place as where it's located, so it's typically a good idea to create a folder somewhere (like in your Documents folder) where you place the MiEx.jar file inside of.
Running MiEx should be as simple as double clicking the MiEx.jar file. You might need to right click the jar file and choose "Open With" and then Java. If this doesn't work, then most likely it is an issue with the file associations on your computer. Running the installer for Java (found above) should fix this issue and you should be able to run MiEx by double clicking it.
When MiEx launches for the first time, it is going to create a few files. It will create a folder called resources which is where you can place your resource packs. Inside of the resources folder is also a file called manifest.json which contains a list of "built-in files" that MiEx had set up. These built-in files are some default files that MiEx needs to export out worlds. Whenever you launch MiEx, it will check the GitHub repository here for new versions of the files and install them automatically. This allows us to provide some updates without you needing to manually update MiEx. New versions of the MiEx.jar file aren't automatically installed. For that, you'll get a banner to notify you of new versions and you can manually download it then.
MiEx also creates a log.txt file which contains a log of what MiEx does. If something goes wrong, this log will typically tell you what went wrong. When creating a GitHub issue for something, it is useful to also provide the log file.
Next to creating these files, it will also install the base_resource_pack. Some of the files from it are built-in files, but most of them are the default Minecraft Java Edition resource pack. MiEx does this by searching for a Minecraft Java Edition install on your computer and then extracting the files from there.
MiEx's user interface is meant to be relatively simple. Most of the complexity is hidden in the resource packs, since you typically set up the resource packs once, but you use the user interface many times.
At the top you have the "Toolbar", on the right hand side you have the "Resource Pack Manager", and in the centre you have the "Viewport". In the Toolbar there is also a button called "Advanced Settings", which swaps the Resource Pack Manager for the Advanced Settings Panel.
At the bottom you have the progress bar which also functions as a tooltip display.
The toolbar is divided up into a few sections. The "World" section contains some buttons: "Load" opens up the World Browser, letting you open up a world. "Load From Export" lets you select a previous export and then it'll open up the world used in that export and load its export settings. "Load Settings From Export" lets you select a previous export and then it'll load in the export settings without changing which world is opened up. "Pause Loading" will temporarily unload the world, allowing you to safely open it up in Minecraft or Hytale, make edits, and then you can un-pause the world to load it back in again. Next to that, you also have a dropdown which lets you select the dimension to load in.
The "Selection" section let's you specify the bounding box of the export region. The coordinates of the bounding box are inclusive, meaning that the blocks specified by "Min" and "Max" are also exported out. "Origin" is the block position that should be placed at (0,0,0) in the exported out world. This lets you offset the entire world. If the "auto" checkbox is enabled, then it'll automatically set the origin based on your export region. The "Chunk Size" setting lets you change the size of the "Export Chunks" and it is specified in terms of Minecraft chunks (16x16 blocks).
The "Zoom" section contains buttons to zoom in and out in the Viewport, together with a teleport button. The TP button will open up a dialog where you can specify a coordinate to teleport the Viewport to, or select a player to teleport the Viewport to.
The "Edit FG" button lets you enter or leave the "Edit FG"-state. When enabled, you can click on the export chunks in your export region to change whether they are tagged as "FG" (foreground) or not. This is mainly an organisational thing.
The "Advanced Settings" button turns on or off the Advanced Settings Panel.
The "Export" button opens up a file dialog to let you specify where you want to export out the world to and when you then hit "Save" in the file dialog, it will start exporting the world out. If you had used "Load From Export", then a second button will show up called "Re-export". Pressing this button will immediately start exporting the world out, overriding the export file that you had selected using "Load From Export".
The Resource Pack Manager has three parts: A "Presets" button, the "Resource Pack Selector", and a "Tools" button.
The "Presets" button lets you save your currently active resource packs and export settings out into a preset, which you can then load in later on using the same button. This is useful if you constantly need to export out worlds using the same settings.
The "Resource Pack Selector" has two panels, an "Available" panel and an "Active" panel. The Available panel contains all available resource packs that aren't already active. You can press the "+" button to enable them. The Active panel contains all resource packs that are currently active. You can press the "-" button to disable them and the arrow buttons to change the order of the active resource packs. Resource packs higher up in the Active panel override resource packs lower in the panel. The base_resource_pack is a special resource pack that contains a bunch of default files and so is always active and cannot be disabled. It also indicates what version of Minecraft Java Edition it contains the default resource pack of.
The "Tools" button provides a menu with a bunch of different tools:
This will reload the currently active resource packs. Resource packs are reloaded whenever the list of active resource packs changes, but if you ended up quickly changing a file in a resource pack or you added in a new resource pack to the resources folder, then this tool will load all of that in.
This will update the base_resource_pack to a different version of Minecraft Java Edition. It will provide a dialog where you can choose which version to use. The dialog shows you a list of all versions that MiEx was able to find installed on your computer. If a new version of Minecraft has come out, then you can use this tool to update the base_resource_pack to that version, so that MiEx can export out any new blocks added in that version.
This will update the base_resource_pack_hytale. If a new version of Hytale has come out, then you can use this tool to update the base_resource_pack_hytale to that version, so that MiEx can export out any new blocks added in that version.
This will update the built-in files found on the GitHub repository here, to the latest version. MiEx will typically do this when you launch it, but if you want to explicitly do it, then you can do so via this tool.
This will provide you with a dialog where you can select example resource packs, found on the GitHub repository here, for MiEx to download and install. This can also be used to update them, if needed.
This opens up the Resource Pack Installer. On the left side you have a list of "sources" which MiEx grabs from all of the launchers that it can find. Sources can be resource packs, data packs, addons, mods, and mod packs. You can click on the "+" button on a source to add that source to the list on the right side, which is the list of sources to install. Additionally, you can also add other sources by selecting them via a file browser using the buttons on the lower left corner. Once you've selected all sources that you want to install, you can specify the resource pack name that all of those sources should be installed to in the lower right corner and then press the "Install Sources" button.
This tool makes it easy to install various resource packs, mod packs, and so on.
This opens up the Atlas Creator tool, which you can use to create atlases from resource packs. Typically, each texture is its own file which means that you can have hundreds of textures in a resource pack. Each texture would require its own material and so a single export could also contain over a hundred materials if the world has enough different blocks. Atlases are large textures that group together these textures. This way, MiEx can use these atlas textures instead, significantly reducing the number of materials used and therefore making the export less "heavy" in your animation software.
This opens up the PBR Generator tool, which provides a system for batch processing textures. It allows you to generate PBR textures from non-PBR resource packs, convert resource packs from one PBR format to another, or to change the look at textures themselves.
This opens up the Environment Settings Editor. While most settings on how MiEx behaves are set up via files like miex_config.json in resource packs, some settings are global and not dependent on your active resource packs. These settings can be specified either via command line arguments when launching MiEx, or as environment variables. Those environment variables can be set on your computer itself, or placed in a miex.env file. The Environment Settings Editor lets you easily create and edit the miex.env file.
The Viewport gives you a top-down view of the world. You can drag with your right mouse button to move around in the world and use your scroll wheel to zoom in and out. You can make and change export selections by dragging with your left mouse button. If you hold alt, while making or changing an export selection, then it'll snap to chunk boundaries (16x16 blocks). If the "Edit FG" button is enabled, then clicking with your left mouse button on an export chunk will toggle whether it is a foreground chunk or not. The grid of export chunks is shown as a grid with grey lines. You can turn export chunks on or off by ctrl + left clicking on them. When export chunks are turned off, they won't get exported out. You can also specify a Level-of-Detail region for an export region, which you can create and change by holding shift + dragging with your left mouse button.
The Advanced Settings Panel contains additional settings that have been put into this separate panel to keep the main UI clean.
The "LOD" settings let you specify a Level-of-Detail region for the export region. The area within the LOD region is at the normal full quality, but the world outside of it will be at increasingly lower resolutions. This is meant to simplify the far background, reducing geometry, which is useful when exporting out very large worlds. The "Y Detail" setting lets you keep the vertical resolution at full quality for longer, while the horizontal resolution goes down first. A Y Detail value of 1 makes the vertical and horizontal resolution always be the same. "Base Level" is the LOD level that everything starts out at (including the area inside of the LOD region). Level 0 is full quality. Level 1 means that everything is at half resolution. Level 2 means that everything is at quarter resolution.
The "Run Optimisers" option lets you turn on or off whether the optimisers run. MiEx has two optimisers, a face optimiser which combines faces into larger faces, and a ray tracing optimiser which creates a "render" variant of the world with the same geometry but organised differently to provide better ray tracing performance.
The "Remove Caves" option will run an algorithm that tries to cause caves to not get exported out. It's not perfect, but good enough in most cases. Settings for the algorithm can be changed in miex_config.json. The "Fill In Caves" option will make sure to place stone where it it had found a cave, preventing holes in your world where caves used to be.
The "Individual Blocks" option will cause MiEx to export out every block as an "individual block", which makes each block its own object. This creates very heave scenes, but can be useful when wanting to be able to do things like animate something exploding or being built up.
The "Block Animations" option will turn on or off whether it will export out animated blocks. If turned off, blocks with looping block animations will just be exported out as if they are normal blocks without block animations.
The "Exclude Regions as Air" option will cause exclude regions to act as if all blocks in those regions are replaced with air blocks. Normally, blocks will occlude the faces of other blocks and exclude regions would therefore create holes since it prevents blocks from inside of them from being exported out, but not from being able to occlude other blocks. If this option is on, then they also won't be able to occlude other blocks.
The "Export Regions" section lets you create multiple export regions. They are all exported out together in the export, but some settings can be changed from export region to export region. This can also be used to ensure that a section of a world is exported out into its own region, like having a house in its own region separate from all of the land that the house is on. A single export region can be "active", which is the export region that you can actively edit the settings for. To edit the settings for a different export region, click on that region in the list to set that as the active export region.
The "Exclude Regions" section lets you specify bounding boxes for an export region where it shouldn't export out any of the blocks inside of that bounding box. The positions specified by the bounding boxes are inclusive, meaning that the blocks specified by Min and Max are both included in the bounding box.
To open up a world, press the "Load" button in the Toolbar. This will open up the World Browser. The World Browser will show you different tabs at the top for various "Launchers" that it can find. For each tab, it shows you all of the worlds available for that launcher. You can also register folders as "launchers", making it show up as a tab in the World Browser, to easily find worlds that aren't stored in a Minecraft or Hytale launcher. If you just want a file browser that you can use to select a world, then click on the "Browse" tab. MiEx tries to find launchers installed on your computer, but you can always manually point MiEx to the right location by editing the environment variables, using the Edit Environment Settings tool.
When click "Open" on a world, MiEx will load in the world. It first checks if that world makes use of any resource packs, data packs, behavior packs, or mods. If so, it gives you a popup asking if you'd like to enable the resource packs installed in MiEx that match those used by the world. If you click "Yes", then MiEx will enable those. If it can't find any available resource packs that contain the things used by the world, then it provides you with another popup allowing you to have MiEx automatically install those files into a resource pack. This system should allow you to easily open up modded worlds and have MiEx be able to directly export out those modded worlds without having to do anything extra. Unfortunately, some mods specify certain blocks in custom ways that MiEx cannot understand. In those cases, you might need to edit the resource pack to make sure that those blocks are defined in a way that MiEx can understand.
You can navigate the world in the Viewport by dragging with your right mouse button, or with the Teleport dialog by clicking the "TP" button in the Toolbar. Once you've found the area that you want to export out, select it by dragging with your left mouse button over the area that you want to export out. If you want to limit the region on the Y axis, you can specify that in the Toolbar under the "Selection" section. If you ctrl + left click on export chunks, then you can enable or disable them for more control over what gets exported out.
If you want to use any specific resource packs in your export, then you can enable them using the Resource Pack Manager on the right side of the main window. Simply click on the "+" button on any of the available resource packs to enable them. You can click on the "-" button on active resource packs to disable them and click on the arrow buttons to change the order. Active resource packs higher up on the list will override resource packs lower on the list.
Once you're happy with all of your export settings, then you can click on the "Export" button in the Toolbar. This will open up a file browser which you can use to specify where it should export out your world to. When you click on "Save", MiEx will start the export process.
To import in your exports, simply reference or import in the main .usd file that you had specified in the file browser when hitting the "Export" button. If you want to import it into animation software like Autodesk Maya, Blender, Side Effects Houdini, Cinema4D, and so on, then please read the Importing Into Animation Software page, since you will need to do things slightly differently in order to get the materials working properly.