voxelers/mcthings

A Python framework for creating 3D scenes in Minecraft and Minetest

McThings

A Python programming framework for building a 3D World of Scenes in Minecraft (Procedural CSG). Scenes are compositions of Things (Python objects), created and transformed in memory and rendered using the Raspberry PI Minecraft renderer implemented using the API (which also works in Minetest). This renderer is based on mcpi library. More renderers are planned. It follows the pipeline: create and transform in memory (model in memory) and then render.

This is the reference notebook with a complete sample. And there is a intro video tutorial and a more complete one.

A Thing is a built based on blocks (voxels based on cubes): Pyramid, River, House, Fence and may others. All the Things share the Thing API. A Thing can be decorated using existing decorators like LightDecorator or you can create your own one. A decorated house. Scenes can also be decorated like this sample with a railway (BorderDecorator) around a Scene.

And Things can also be rotated. For example, in this scene the castle is rotated 180 degrees so the portal is accessible from the town ways.

There is also a repository for experimental, incubating or with extra dependencies Things at McThings Extra.

A World is a list of Scenes placed in concrete positions. And a Scene is a list of Things built in a specific position and order. Scenes can be shared loading and saving them to files. Scenes can be also saved as Schematics and converted with Mineways to be used for 3D rendering and printing. You can share scenes adding them to this repository. And they can be interactive as in this app.

This scene includes a river, a house in each side of the river and a bridge for crossing the river.

Things can be built using MinecraftDrawing. Sphere and Circle Things are used with Pyramids in the next scene:

And Things can also be built from Schematics (there are thousands!). There is a sample notebook.

And Things can also be created from MagicaVoxel models.

Minecraft and Minetest forums pages.

mcthings's Issues

Create the Road Thing

Road (defined by dots joined by lines)

Joint the 3 levels of AbadIA

After finishing #47 it is time to join the three levels in a common building.

Analyze howto implement basic operations in Things

• move: can be implemented at things level. Just unbuild, change the position and build
• mirror
• rotate
• scale: in several cases it can be implement easily, but it depends in each thing
• invert (for inverse pyramids)

For example, to create a town with a line of houses in one side of a street and another at the other side, we can just build the second one as a mirror of the first one.

Add support for Minetest

Analyze and implement what is needed in McThings so it works with Minetest: https://www.minetest.net/

Minetest has support also for the Python API: https://github.com/arpruss/raspberryjammod-minetest

So it should work out of the box mainly.

Research install Python API in Minecraft local execution

It seems it is possible to execute Python API directly in the client side with:

https://github.com/arpruss/raspberryjammod

You install a mod for the minecraft client (Forge are mods for client side?)

Evolve scene test to a full town sample

The town must include all things that exists now and also:

• Farm (post 1.0)
• Fountain (post 1.0)
• Road: covered with lines in 1.0

Create the Farm Thing

Farm .. ¿which one? https://minecraft.gamepedia.com/Farming (food one probably)

Explore Interactive Scenes

Events in Minecrafts, like hitting a block, can be collected from the Python API. So when the player hits a block (for example a button), the scene could change and show/hide Things, for example.

Add CONTRIBUTION.md

Define how mcthings position things in the world

In which direction of the x,y,z build things?

x: width
y: height
z: large

We build in both cases from the lower value to the higher value. So if initial x is -10 and the width is 30, the end x is 20. The same for y and z.

By default we use the player position as the initial pos for x, y, z. Following this approach, the initial thing is built nex to the player, without covering it (at least with the first thing).

Design the scenes repository

The goal is to share creations in the easiest way.

The size of the creations is minimal (560 bytes in the current creation sample).

Study the Minetest plugin for Raspberry PI Minecraft API

After the research at #50 the decision is to invest in the support of the Python API in Minetest.

https://github.com/arpruss/raspberryjammod-minetest

After our research at #45 the plugin is usable as it is right now. The next steps:

• Describe the API covered
• Learn howto create plugins for minetest using Lua
  • Learn Lua in the process (Refs here: https://www.computercraft.info/download/)
• Test the full API and find the gaps not covered from the origin Raspberry PI API
• Test it with Minetest 5.2
• Meet the community

I have already fork the repository at: https://github.com/acs/raspberryjammod-minetest/blob/master/README.md

The original developer seems to have lost motivation about the plugin, but he is answering issues: arpruss/raspberryjammod#49

Create pip package

Use as reference: Bitergia/prosoul#51

Create a tutorial on how to do a scene using things

• The original idea. Get inspired!
• The initial paper based design
• Adding things for building the scene
• Undo things
• Saving the scene
• Cleaning the scene
• Loading the scene
• Sharing the scene

Explore storing scenes in Schematic compatible format

With that, tools like WorldEdit can be used to interoperate with scenes.

WorldEdit seems to be the leading tool for MC/MT world editors: https://worldedit.enginehub.org/en/latest/. It has just released its 7.1version https://matthewmiller.dev/blog/introducing-worldedit-71/ in Jan 2020, so it is alive.

List of new things

• Labyrinth
• Create fence valid to round any Thing Done

Review samples using mcpi to use them in the Town Scene

https://github.com/arpruss/raspberryjammod-minetest/tree/master/raspberryjammod/mcpipy

Capture Things inside the world

A really cool feature is that you can build your house inside Minecraft and the capture it in McThings in order to use it (copy, scale ...).

I think that schematic feature in Minecraft goes in that direction: reusing designs created inside Minecraft.

https://minecraft.gamepedia.com/Schematic_file_format
https://www.minecraft-schematics.com/
https://www.curseforge.com/minecraft/mc-mods/schematica
https://minecraftstuff.net/schematics
https://www.planetminecraft.com/resources/projects/?share=schematic

Summary of the Python support in Minecraft/Minetest

Once we have tested that Python can be used in:

• Spigot 1.15.2 (with 1.11 and 1.12 plugin versions)
• Minecraft Forge: for using it in the client with 1.12.2 version. The mod does not work in newer versions of the Forge.
• Minetest: 1.12 working with Minetest 5.1 (not tested yet with 5.2 but it probably will work)

It seems that all the mod/plugin version for the Rasperry PI API share the same code, because all stopped in 1.12 version. But I need to review it. For example, for minetest, it has not been changed since 4 years ago.

Thoughts and evolutions of the Things API

• Convert Object to Thing as the base class ok
• Add full_size and init_position as read only params in a Thing
  • size is a method/verd
  • orig_pos is a private constant

Dissemination once 0.10 version is available

• Minetest community
• Minecraft Java community
• Minecraft Bedrock community? It should work
• Minecraft PI community

and specifically with projects like:

https://github.com/martinohanlon/mcpi (python lib)
https://minecraft-stuff.readthedocs.io/en/latest/ (similar concept than McThings but more basic)
https://github.com/zhuowei/RaspberryJuice (Java)
https://github.com/arpruss/raspberryjammod-minetest (minetest)

Add license and authoring information to all the files

Try to keep the ASL license as short as possible.

https://issues.apache.org/jira/browse/LEGAL-124

The header is:

# Licensed under the terms of http://www.apache.org/licenses/LICENSE-2.0

and about the authors and copyright:

# Author/s (©): <name of the author/s>

Not sure if the © introduces problems. Probably we can just use (c).

Implement walled town using the end_position

The idea is to implement the wall around a town using the end_position property the town.

Create scene 0.20.0 based on 0.10.0 with schematics

Including the version in Scene it will be serialized to the scene file and it can be used later for debugging purposes, migration strategies ...

Design how to continue editing a creation loaded from a file

Probably this work in a natural way. If you continue adding things to the Creation, you are evolving it. And also, you can remove builds. Probably, when a thing is unbuild, it must be removed from the creation also. So closing this issue because it works out of the box!

Analyze commands not supported by mcpi

The complete API supported at the server is:

https://github.com/zhuowei/RaspberryJuice

There is a mcpi modded to include the full API: https://github.com/zhuowei/RaspberryJuice/tree/master/src/main/resources/mcpi/api/python/modded/mcpi

With it, for example, entities can be created. And there are a lot of them:

https://github.com/zhuowei/RaspberryJuice/blob/master/src/main/resources/mcpi/api/python/modded/mcpi/entity.py

We are using right now the 1.11 version which includes:

1.11 - spawnEntity, setDirection, setRotation, setPitch

In 1.12 we have also:

1.12 - getEntities, removeEntities, pollProjectileHits, events calls by player and entity

so we need to move to it. In javierete.com we have:

root@javierete:~# ls -1 /home/minecraft/spigot/plugins/
PluginMetrics
RaspberryJuice
bStats
raspberryjuice-1.11.jar

We need to migrate to the last one.

https://www.spigotmc.org/resources/raspberryjuice.22724/

Fix moving of the scene 0.10

https://github.com/juntosdesdecasa/minecraft/blob/develop/server/data/python/scene1_0.ipynb

This complex scene is not well moved. It is great for debugging the move of things.

Create the v0.20.0 release

Once the development has finished it is time to create the v0.20.0 release:

• Create the release and upload it
• Release notes
  • Include version in Things
  • Support for schematics
  • Complete unit testing support
  • License headers added
  • Scenes: AbadIA, Schematics
  • Check all with Minetest
• Create a video with the new features (mainly schematics)
• Announce it
  • Minetest forums
  • Twitter/Linkedin

Explore rotate operation

If it is not too expensive to implement in Things (or Scenes), it can be interesting. Let's explore it!

Add support for building Scenes with blocks programming

Not sure yet what is the best platform, but the Things based platform of McThings is ideal for creating the scenes using blocks.

Blockly

https://github.com/google/blockly
http://robotblocks.appspot.com/static/minecraft/index.html
https://forum.minetest.net/viewtopic.php?f=11&t=13316

https://en.wikipedia.org/wiki/Blockly
«Blockly uses visual blocks that link together to make writing code easier, and can generate code in JavaScript, Lua, Dart, Python, or PHP. It can also be customised to generate code in any textual programming language.[2]»

Others

juntosdesdecasa/minecraft#9

Analyze if the tests must be converted to PyUnit or similar

The tests must be executed with a Minecraft server running. They are integration tests. Right now I feel that the best approach is to leave them as independent tests like samples.

Analyze the impact of the Flattening in McPython ecosystem

From the experience in:

#50
#52

understand the impact of https://minecraft.gamepedia.com/Java_Edition_1.13/Flattening and how it is managed in Spigot with the Legacy Material support.

Fix unbuild of lines

Lines are not in the air, so unbuild them is not to fill the with air but with a dirt block.

Design and Implement howto extend McThings

Someone could upload a pip package like:

mcthings-cool-houses

with more things related to houses, and McThings must load it and make the things available.

Define creations using a Map (Construction/Building Map)

This map could be a list of coordinates with the thing to be build in each one.

It could be used to automate the creation of the scene, to share them, to evolve ...

Analyze howto share the scenes

Right now scenes can be stored in files using pickle. So this is the way to go. In the future, other formats as JSON or RAML could be considered for scenes, so you can edit this files directly to modify the scenes.

But, how to share scenes? In the Minecraft community there are two ways to share creations right now:

• Schematics (created with WorldEdit or MCEdit)
• Worlds

It seems there are two file formats: "Schematics" file and "World Save" file. But probably both of them describe the creation at block level.

Move mature things from mcthings_extra to mcthings

Update also the doc, in special with the support for Schematics, which is the killer feature probably.

Improve doc in readthedocs

• Select a more attractive theme
• Include info the the landing page (converting markdown to rst)
• Review all the code doc

Add end_position data to all the things

After builiding the thing the end_position must be defined to other things could be positioned relative to the last thing built. It is essential for doing compositions.

It is already done for town.

Railway Thing

Analyze howto document

• Doc: https://readthedocs.org/
• Guides and samples: notebooks

Our users are also developers, so thing about the above distinction. The real doc is the first one. The second one (notebooks) is more a kind of guide.

Add support for importing schematic files

And it seems that the Minetest plugin has already some support for it:

https://forum.minetest.net/viewtopic.php?p=192890#p192890

Explore the extended Python API (generating entities!)

Generating entities and capturing events could provide life to our cool scenes.

Improve the bridge

Our basic bridge could be vastly improved. Compare this two bridges:

Cool Things will create cool Scenes. So improving the Things will be a basic task in this project.

Add support for loading AbadIA CSV heights files and build it

STL is a format used for 3D printing. In the project In the project AbadIA they are reproducing the Abadia large building using STL generated from a CSV file with the heights data..

The idea is to read this STL files and reproduce them inside Minecraft. In this case they are using as unit building block a 1x1x1 block, just the same than in Minecraft. So It should be easy to recreate in Minecraft the building.

The steps are:

• Load the cube STL inside MC to understand the format
• Load the composition of two cubes inside MC
• Load the level0 floor
• Load all the floors

Add support for Minecraft - Stuff Library

https://minecraft-stuff.readthedocs.io/en/latest/index.html

Create the Maze Thing

It could be a labyrinth of tunnels ...probably easier to build and very attractive. To exist from a cave is exciting.

Build integration tests from current tests so they are executed automatically

In order to have quality releases, we need to execute all tests automatically.

Create the Fountain Thing

Include the McThings version in an attribute in the Scene

This is important to debug issues in the future when new versions that can break the API appear.