Menu
▾
▴
Tree [377664] default tip / History
Benjamin Johnson
Read Me
----------
libanvil
----------
Libanvil is a C library for manipulating Minecraft world data, designed
to be as simple and efficient as possible. It provides full read and write
support for region data in the Anvil file format, with support for other
game files planned. It includes APIs for both low- and high-level access.
This README provides a brief overview of libanvil's features and how to use
it in your code. For further reference, please refer to the various header
files and included demonstration programs; they are well-commented, and should
be fairly self-explanatory.
Table of Contents
-----------------
1. Features
2. Requirements
3. Demo Programs
4. The Low-level API
5. The High-level API
6. Limitations
7. Acknowledgements
8. Contact the Author
1. FEATURES
-----------
- Full read and write support for the Anvil file format.
- Small library size and extremely low memory usage (< 2MB for most demos).
- Well-organized and thoroughly documented source code.
- A variety of useful and astonishing demo programs, whose functions range
from basic maintenance to arcane wizardry, or particularly in the case of
png2world, perhaps just showing off. See "Demo Programs," below.
2. REQUIREMENTS
---------------
Libanvil itself has no external dependencies besides zlib, which should
already be present on most systems. If your system does not have zlib, you
can download a copy from <http://zlib.net>.
The png2world.c demo program additionally requires gd-2.x with libpng support.
If your system doesn't have these libraries available, you can disable building
png2world by removing it from USEFUL_PROGRAMS in the Makefile.
3. DEMO PROGRAMS
----------------
- copy_chunk.c:
Copies a single chunk from one world's region data to another's.
- dig_out.c:
Removes all blocks in a chunk above a specified Y level.
- mcdraw.c:
Allows placing a large number of blocks from the command line.
- mctrim.c:
Shrinks region files by removing unused chunk data.
- png2world.c:
Transforms a PNG image into a Minecraft superflat world.
- spew_chunks.c:
Displays an ASCII representation of a specified chunk of world data.
- test_gen.c:
Demonstration of how to generate a new chunk procedurally with libanvil.
4. THE LOW-LEVEL API
--------------------
The low-level API allows direct manipulation of chunk data; it also makes
possible tighter manual optimization than the high-level API. This was the
first API added to libanvil, and is the one used by most of its included
demo programs. Despite the name, it is still fairly straightforward to use.
The typical procedure for using the low-level API is:
1. Include the low-level API header files:
#include "cNBT/nbt.h"
#include "region.h"
#include "chunk.h"
2. Open the region file of interest using one of the region_open_*()
functions, then read its header using region_read_header().
3. Access chunks of interest using region_get_chunk(), then manipulate
them using the various chunk_*() functions in chunk.h.
4. Call chunk_update_heightmap() to update the chunk's height map.
5. Write chunks back to the file using region_write_chunk(), then
free them using chunk_free().
6. Close the region file using region_close(), and free its header using
region_free_header().
5. THE HIGH-LEVEL API
---------------------
The high-level API makes it dramatically easier to manipulate block data,
since you don't have to select region files and chunks of interest manually.
It's also called the "lazy API" because its outward simplicity comes at the
expense of slightly less efficient code.
The typical procedure for using the high-level API is:
1. Include the high-level API header file:
#include "lazy.h"
2. Open the world of interest using lazy_world_open(). Note this function
always opens the world in read/write mode.
3. Manipulate blocks in the world using the various functions in lazy.h.
Note that it's normal to feel guilty about how easy this is compared to
the low-level API. This will all pass in time.
4. Close the world using lazy_world_close(). Note that there is no
lazy_world_write() or equivalent function, since changes to the world
are saved automatically. Yes, it really is that easy.
6. LIMITATIONS
--------------
- Libanvil currently chokes on files generated by Minecraft 1.7.x.
Until this is fixed, I recommend sticking with 1.6.4.
- Libanvil operates directly on your region data, meaning a crash will
corrupt your game files. ALWAYS HAVE BACKUPS.
- Due to the way region_write_chunk() is currently implemented, region
files can grow to ridiculous sizes very quickly -- even more so if you're
using the lazy API. I told you it's inefficient.
- On that note, mctrim.c seems to corrupt game data more often than not.
I'd recommend against using it until we know what it's actually doing.
- No support yet for manipulating entity data.
- No support yet for adding Y-levels to existing chunks.
- Lots of weird behavior with negative X and Z block coordinates.
7. ACKNOWLEDGEMENTS
-------------------
Libanvil is based on cNBT by Lukas Niederbremer and Clark Gaebel.
8. CONTACT THE AUTHOR
---------------------
Benjamin Johnson <obeythepenguin@users.sourceforge.net>
