Mineways/Jmc2Obj Bridge: Directly load & refresh worlds in Blender

[TheDuckCow]

Feature overview

Vision

To directly load in Minecraft saves without ever leaving Blender. To be able to not just load, but also refresh/reload, and to extend the world in case you later need more imported.

How?

By using the scripting feature of Mineways and jmc2obj, which is a way to control the application without user interactions. Calls to the program will still generate OBJ files which are then imported into blender automatically, seamlessly for the user.

Why not natively implement loading of worlds like e.g. MineBlend? Well, that's a ton of work, and hard to keep up to date, and as soon as this feature is created, users will depend on it heavily and it needs to be stable. Instead of reinventing an entire wheel, MCprep will lean on the existing and still maintained Mineways & jmc2obj projects.

Implementation steps/milestones

Rough order of tasks, and progress

1. Proof of concept:
   • [x] Pure pythonic proof of concept controlling Mineways on both windows and mac
2. Implement raw loading of worlds into Blender
   • [x] Basic implementation inside of Blender (manually specified coordinates, few options)
   • [ ] Splitting of import regions into chunks, with individual chunk empty parents to re-identify chunks later
   • [ ] Workflow or tools to let user easily select what region they want to import. TBD how this looks, needs more thought, but some ideas:
     • Load config from previous Mineways obj export (reading only metadata atop the file)
     • Import 2D preview image as plane of selected world, which refreshes when changing the bounds of the import before pressing load world
   • [ ] Deal with (ie remove) intermediate obj files and material proliferation from multiple imports
   • [ ] Pass forward more of the config options from Mineways (e.g. exporting to texture folder instead of single texture, export individual blocks, flattening options)
3. Reloading world management
   • [ ] Reloading a single/multiple/all chunks
   • [ ] Reloading chunks with setting changes (ceiling/floor level, reload as individual separated blocks, etc)
   • [ ] Reloading without replacement (ie don't delete the previous chunk, but just hide it)
   • [ ] Reload and auto apply material sync between other chunks and newly reimported chunk (different to prep materials, as user could have further customized some materials)
4. World management
   • [ ] Workflow to extend the chunks of the world imported
   • [ ] Ability to "bait and switch" specific chunks one frame versus another for two different point in time imports (e.g. refresh and keyframe visibility of new chunks on current frame and onwards)
   • [ ] Suggest chunks or sections to hide if not in camera (faster renders!) based on camera orientation
5. Install and configuration
   • [x] Have easy to understand UI directions for Windows on how to download Mineways and point MCprep to it
   • [ ] Have easy to understand page/tutorial/in-addon description on how to setup & use Wine with Mac OSX and Linux (requires additional user steps)
   • [ ] Option to directly install and configure mineways from within MCprep (so user doesn't need to download and place it somewhere themselves; but, this is a risk as this is downloading executables from a third party location, albeit a trusted one; may opt to just encourage users to do this manually)
   • [ ] Notify user if newer version of Mineways is available

Implementation architecture

This will be implemented with a split between a pure-pythonic wrapper which calls/communicates with Mineways, and then a parent blender python file which implements the blender-specific operators and user workflow.

Currently, Mineways can only be launched with scripts as a starting input script file, and after this script executes, the program either is still open (ie "orphaned") or closes (if the close command is included in the script). Because we want there to be no user interaction with Mineways itself, every command needs to end with a close statement.

To keep blender responsive, this should be implemented in a parallel process so that there can be interactions such as ESC to stop the current import where it is, or to cancel altogether. Because we cannot communicate to an already opened and running instance of Mineways (yet), this means batching the world out into chunks (where Mineways opens, exports a chunk or two, then completely closes down) and then offering to stop after some have ran, but always letting Mineways finish its current process.

To be decided: have this all running in a modal operator (most stable), or allow the parallel process to continue while user can interact with blender as chunks are loaded (likely quite unstable).

Additionally, the world should be managed and thought of more as a "bridge" than a once imported and done approach. Settings for how a world was imported will be saved, and features will allow for piece-wise reimporting of chunks, or even extending the imported world as-needed.

Links and references

• Early teaser of the feature
• Reference for (stale) MineBlend, which technically works still (2.7x) but not complete or comprehensive
  • Could get some reference code for bare minimum save data file reading, but avoid and leverage Mineways for everything possible.

[TheDuckCow]

Realized now that a command-line interface also already exists for jmc2obj, and should sufficiently work to include as an alternate option when using the bridge feature.

Sample execution to output a world to obj (and exporting the texture folder):

java -jar ./jMc2Obj-107.jar \
  --dimension=0 --area=-40,-40,40,40 --height=0,256 \
  --render-entities --object-per-mat \
  --output=/..../test_jmc_cmd/ \
  --objfile=test_jmc2_cmdlin.obj --mtlfile=test_jmc2_cmdlin.mtl \
  --export=obj,mtl,tex "..../saves/world_save"

More options visible via --help. Note to self that I noticed at first the tex exporting was rather slow. Also calling out that newest jmc2obj appears to not be able to open old-format chunks, and so can only be used with newest world formats, which should generally be fine for users anyways, as they should be able ot just open their old worlds in the latest Minecraft version..

[TheDuckCow]

While little additional development done, I have much more of the design approach worked out. See the architecture diagram here (click for higher resolution):

This approach was designed keeping in mind submissions from the survey, where the biggest insights were:

• Yes, people do tend to have multiple worlds imported inside a blend file at once
• Yes, people tend to wish they could reload a world already imported
• Overwhelmingly yes, they wish they could extend a world after an initial import.

I was not strongly in favor of supporting multiple worlds linked at once, but I see now it's important enough to strive for.

Source from survey (although only 12 responses):

[TheDuckCow]

Minor update, this feature has not been forgotten, but has not been heavily prioritized due to other things that need to be done first before this can be launched effectively:

• New updates for all the block mappings for Vanilla 1.14+, this is a manual step and I am reconciling how to best implement this so it is reasonably future proof and easy to update as things continue to change.
• Resolving existing stability and usability issues
• Making sure I'm braced for a waterfall of issues and support questions, as this inevitably will be a complex feature where things can go wrong in many different ways. I'll need to implement clear way to help the users help me debug for them, to isolate when the arisen issues are 1) From blender, 2) from Mineways or jmc2obj itself (in which case I redirect to those support pages), or 3) MCprep handling of the interfaces.

[TheDuckCow]

Another update, aiming to push out the next version (likely naming 3.3.0), after which this feature should be feasible for limited alpha testing. Due to the limited nature, I'm planning to make an opt-in toggle feature and/or a notice to press OK that feature is experimental, so that it's not depended on for production work (at least not without extra precautions).

Also saving this nbt link as I leveraged part of this and planning to bundle or extract the needed piece for reading player locations as a starting point.

[StandingPadAnimations]

Revisiting the issue (as well as some other old issues). I think we should create an MCprep Hackathon type of event for stuff that's on the back burner, but also too complex to label a "good first contribution"