Menu

Tree [377664] default tip /
 History

Read Only access


File Date Author Commit
 cNBT 2013-12-12 Benjamin Johnson Benjamin Johnson [c1f8cb] Initial commit under the project's final name, ...
 contrib 2013-12-21 Benjamin Johnson Benjamin Johnson [7fed78] Added a GIMP color palette for use with png2wor...
 .hgignore 2013-12-27 Benjamin Johnson Benjamin Johnson [5e2c5c] Added mctrim.c, a program to remove unused chun...
 Makefile 2013-12-28 Benjamin Johnson Benjamin Johnson [45f3dd] Some minor Makefile cleanup
 README 2013-12-28 Benjamin Johnson Benjamin Johnson [3edda6] Added a section on known limitations to the README
 chunk.c 2013-12-28 Benjamin Johnson Benjamin Johnson [953ceb] Add implementation notes to chunk.c explaining ...
 chunk.h 2013-12-28 Benjamin Johnson Benjamin Johnson [e5e85a] Move the BP() macro from lazy.c to chunk.h so o...
 copy_chunk.c 2013-12-28 Benjamin Johnson Benjamin Johnson [5cab3a] Standardize demo program usage messages
 data_values.h 2013-12-27 Benjamin Johnson Benjamin Johnson [506596] Make all header files C++ safe
 dig_out.c 2013-12-28 Benjamin Johnson Benjamin Johnson [74e6ab] Update dig_out.c's source file description
 lazy.c 2013-12-28 Benjamin Johnson Benjamin Johnson [e5e85a] Move the BP() macro from lazy.c to chunk.h so o...
 lazy.h 2013-12-27 Benjamin Johnson Benjamin Johnson [506596] Make all header files C++ safe
 mcdraw.c 2013-12-28 Benjamin Johnson Benjamin Johnson [377664] The Y-loop in mcdraw.c should be on the inside ...
 mctrim.c 2013-12-28 Benjamin Johnson Benjamin Johnson [ff9989] Don't use region_close() in mctrim.c, since we ...
 png2world.c 2013-12-28 Benjamin Johnson Benjamin Johnson [5cab3a] Standardize demo program usage messages
 raw_data.h 2013-12-27 Benjamin Johnson Benjamin Johnson [506596] Make all header files C++ safe
 region.c 2013-12-28 Benjamin Johnson Benjamin Johnson [c8b377] Use consistent parameter names for chunk data
 region.h 2013-12-28 Benjamin Johnson Benjamin Johnson [c8b377] Use consistent parameter names for chunk data
 spew_chunks.c 2013-12-28 Benjamin Johnson Benjamin Johnson [5cab3a] Standardize demo program usage messages
 test_gen.c 2013-12-27 Benjamin Johnson Benjamin Johnson [195759] Silence test_gen.c

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>
Want the latest updates on software, tech news, and AI?
Get latest updates about software, tech news, and AI from SourceForge directly in your inbox once a month.