User:Ha3

=MAtmos Designer guide to database creation= MAtmos Designer is a graphical interface that serves as a database editor. It allows to create databases to be used with MAtmos, but also contains a replicate of the MAtmos Engine, which enables the use of a simulator. Therefore, the databases can both be created and tested with the editor, as MAtmos Designer uses the same sound engine Minecraft uses.

MAtmos Designer can be used without owning Minecraft with absolutely no legal issues. MAtmos Designer does not rely on any Minecraft resource, and the sound engine is the same as Minecraft in the sense that both are using one same sound library, paulscode Sound package along with LWJGL binding, which licenses are fulfilled.

In this sense, MAtmos Designer can be installed and run on a computer that doesn't have the capability of running Minecraft.

However, MAtmos Designer requires some files that are provided with the MAtmos mod. This is due to the fact that the files can be independently updated without a MAtmos Designer update, and these updates are closely related to the changes in Minecraft, for instance, the addition of new blocks.

Installing
MAtmos Designer, once downloaded, can be installed on different OS. Since the editor can be used standalone, we'll refer Working Folder as either the .minecraft/ folder if you own Minecraft and desire to install it there to make things easier, or to your installation folder of choice.

The benefit of installing directly in .minecraft/ is that once you update MAtmos, you won't need to do extra file manipulation, the editor is ready to be launched. Also, since all sounds are relative to Working Folder/resource/newsound/ folder, adding new sounds in that folder will not require the sounds to be duplicated to your .minecraft/ folder.

On Windows, put the contents of the Designer Archive/windows/ folder into your Working Folder.

On Linux, put the contents of the Designer Archive/linux/ folder into your Working Folder. Please add the library files to your distribution libraries in case of malfunction.

On Mac, the files are provided in the Designer Archive/mac/ fonder, but it hasn't been tested. Please try as aforementioned on the Linux section!

MAtmos Designer relies closely on one extra file you can find in MAtmos, which is default_reference.xml. Please put the MAtmos Archive/default_reference.xml into your Working Folder if not already done.

Reference file
The file default_reference.xml contains information that is not generated by MAtmos Designer. Its purpose is to provide information about how the data looks like, and convert abstract numerical data into meaningful data readable by a human.

MAtmos Designer and MAtmos Engine is completely abstracted from Minecraft references. MAtmos Engine's job is to compare values and to produce sounds. It has no idea of the nature of those values.

MAtmos will provide a default reference file. It corresponds to the latest implementation of MAtmos in Minecraft, and usually between each update, the reference in updated to add new blocks and eventually new special data entries.

It is possible to add custom block names by altering the reference file with a text editor. You could then load the reference and use new blocks easier. This can be useful for mods such as Aether.

How MAtmos works
MAtmos refers to the process of loading databases and gathering information from the world, in order to feed the MAtmos Engine with. It also refers to the process of receiving information from MAtmos Engine, notably to produce actual sounds.

The internal mechanism of MAtmos Engine will be discussed later.

Loading databases
The very first step is to load databases. MAtmos will do so right when the main menu loads.

It will load files in this order:


 * 1) Main database
 * The main database is retrieved from the Internet on a particular URL defined in matmos_options.txt, if the options is set to do so.
 * If it fails to load due to any error, it will load from the latest successfully loaded database obtained this way, stored in online_database.xmlo.
 * If the options is set not to download from the Internet, or if it ultimately failed to load then it will load default_reference.xml.
 * 2) Expansions
 * Each file in matmos_expansions/ will individually be loaded with no particular order, same goes for sub-folders. In case of an individual failure to load, that individual file won't affect anything, and the loading process will continue with the remaining files in the folder.
 * 3) Override
 * The file override_database.xml will be the last database to be loaded. If that database contains entry identifiers that were already created by previous databases, the override database will alter those entries.

An empty database is a valid database, as long as the database is correctly formed. An empty file is not a valid database for instance.

Gathering data
Upon runtime on a world, MAtmos will start to gather data. The data will only be gathered if MAtmos detects that a world clock is running (this is usually the case even for servers that lock their clock). There are two major processes in which data is gathered.

The first process is a frequent update, which gathers data that is rapidly changing, such as the player position or the amount of sunlight on the current tile the player is standing on.

The second process is a slow update, which gathers data that is rarely changing or with negligible changes.

The rarely is evoked in a strictly probabilistic sense. It is highly probable that at a 32 meter radius around the player, within 10 seconds on a same location, the world won't change its internal composition more than 1% (about a thousand blocks) and even less likely more than 5%. A change in 5% composition can be neglected. Of course, this barrier can be breached due to a real-time World Edit or loads of TNT, but the probability of these events happening at any given time is insignificant as opposed to normal gameplay. The same logic goes for the player moving a bit. When the player moves within a certain distance, if the distance is short, we won't likely find major changes in the world composition.

Gathering Instants (frequent)
Instants are part of the frequent process. Instants usually consist on checking the status of the world, and the status of the player. It then put the gathered data into the sheet called "Instants".

The Instants data gathered compromises of:
 * TODO; fill this section

Performing the Small Scan (frequent)
The Small Scan is part of the frequent process. It consists of a scanning of every single block on a 16*8*16 volume centered on the player. This is done in a single frame.

If the player is near the bottom of the world or the top of the world, the volume will still be of the same shape, but only centered on the X and Z axis of the player, the volume being kept in the editable area of the world. This includes layer 0 and layer 127 which are usually impossible to edit genuinely.

The scanning process results in every single block of each kind being counted. The sum of the count of each kind of block is equal to 16*8*16 = 2048. This is stored in the SmallScan sheet.

Additionally, another sheet is produced called SmallSheetPerMil, which entries equal to the count of each block multiplied by 1000 and then divided (floating point) against 2048, rounded up. Therefore, the sum of all entries in that sheet may be equal or over near 1000.

Performing the Large Scan (rare)
The Small Scan is part of the rare process. It consists of a scanning of every single block on a 64*32*64 volume centered on the player position when the scan starts. This is done in 32 frames, usually every 0.1 second, which sums up to about 3.2 seconds.

This scan is only initiated if the player hasn't moved 16 blocks away on the X or Z axis or 8 blocks away on the Y axis, compared to the previously performed Large Scan.

The same rules apply as above if the player is near the bottom of the world or the top of the world.

The scanning process results mainly in every single block of each kind being counted. The sum of the count of each kind of block is equal to 64*32*64 = 131072. This is stored in the LargeScan sheet only once the whole scanning is complete.

Additionally, another sheet is produced called LargeSheetPerMil using similar rules as above, the sum of all entries in that sheet may be equal or over near 1000.

Also, this scanning process performs additional operations whenever it encounters a sign. For each sign, the Sign process is performed.

Sign process
Some signs can be written in a way that it gives information to MAtmos.


 * TODO; fill this section