What is an instance
Instances are what replace "world" from Minecraft vanilla, those are lightweight and should offer similar properties. There are multiple instances implementation, currently InstanceContainer and SharedInstance (both are explained below)
All instances can be accessed by using the InstanceManager or by getting an entity instance
InstanceManager instanceManager = MinecraftServer.getInstanceManager()
// Or
Entity#getInstance
Internally, the default Instance class have its own sets to store the entities in it, but all chunk based methods are abstract and meant to be implemented by a sub-class
InstanceContainer
"Container" here means that this is an instance which can store chunks. And as every instances, have its own sets of entities
You can create an InstanceContainer by calling:
InstanceContainer instanceContainer = instanceManager.createInstanceContainer();
In order to have a valid world generation, you need to specific which ChunkGenerator the instance should use, without it no chunk can be generated. (check here to make your own)
instance.setChunkGenerator(YOUR_GENERATOR);
SharedInstance
A SharedInstance needs to have an InstanceContainer linked to it. The "Shared" means that this is an instance which takes of all its chunks from its parent instance container
What does it mean? That if you break or place a block to the instance container, the shared instance will also reflect the change (same if you place a block using the shared instance methods, changes will be reflected to the instance container and all of its shared instances)
You can create a SharedInstance using:
SharedInstance sharedInstance = instanceManager.createSharedInstance(instanceContainer);
Create your own Instance type
You are able to create your own class extending Instance and add entities to it.
In this case, the only thing you need to be aware of is that all instances need to be registered manually in the instance manager.
instanceManager.registerInstance(YOUR_CUSTOM_INSTANCE);
This method is ONLY required if you instantiate your instance object manually, #createInstanceContainer and #createSharedInstance already register the instance internally.
Save your instances/chunks
It is also important to notice that, by default, the chunks of the instance are only stored in memory. In order to have them stored in a persistent way, you need to serialize and deserialize them. Please check the Chunks management page for further information
Check here if you want more information about storage (do not forget to define a StorageSystem beforehand)
// Here is how to create an instance having a storage location
StorageLocation storageLocation = MinecraftServer.getStorageManager().getLocation("chunk_data");
InstanceContainer instanceContainer = instanceManager.createInstanceContainer(storageLocation);
// Save all chunks based on the IChunkLoader (instance containers save to the current storage location by default)
// you can specify a callback in order to know when the saving is done
instanceContainer.saveChunksToStorage();