User:Ha3

Note: This documentation is obsolete as of r7.

This documentation is not complete.

=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.

Quickly understand MAtmos Designer
In order to easily understand MAtmos, if you're able to, please run Minecraft, load a world, wait at least 10 seconds and press F7 promptly twice. Then go to your .minecraft/ folder and put the file data_dump.xml into your Working Folder.

In MAtmos Designer in the Simulator tab, press Load default dump at the bottom. A series of lists will appear, describing the world.

It is compromised if several Sheets you can select at the top of the Simulator to visualize them.

Minecraft Sheets
LargeScan is the results of a 64*32*64 volume of the surroundings of the player. The entries are the counts of each block. LargeScanPerMil is the same sheet, but shown as per mil, that is the sum of all entries is about equal to a thousand.

SmallScan is the results of a 16*8*16 volume of the surroundings of the player, in the same fashion. Same goes for SmallScanPerMil.

Instants describe the status of the world, or the status of the player.

There are also two special sheets, which are either self-explanatory, or better explained in the complete MAtmos documentation.

Database content
The next tabs are components MAtmos Engine works with.

The Dynamic Values allows you to create values that are the sum of several Sheet entries. For instance, you can sum up the total amount of water, compromised with the Static water and the Flowing water.

The Lists lets you create lists of possible values, to be used exclusively instead of constants with the comparative operation in or !in (not in).

The Conditions allows you to perform comparative operations on the Sheet entries or Dynamic Values entries against a constant or a list.

The Sets allows you to combine Conditions.

The Events are the sounds that are played with characteristics. A global sound is a sound that doesn't seem to have a location in the world, it will play everywhere.

The Machines executes Events when some Sets are active while some other Sets are not active, with different frequencies and volume. It can also contain Streams, which are looping sounds. They can be played as Music if the volume of the stream is zero. In Minecraft, music played by MAtmos has its own music slider.

Constructing a database
The construction of a database is left to you: The objective is turn values contained in the sheets into more meaningful values, accomplished by the Dynamic Values, the Conditions and the Sets.

For instance, a Condition checking if there are a certain amount of leaves can assume there are trees.

A Condition checking is there are a certain amount of sand will leave open interpretations with the meaning of this sand. When you combine that Condition with two others using a Set, one which will check that there is a certain amount of potential sunlight when it's daytime where the player is, and one which will check if there is a certain amount of water around, you can use this Set to assume that the player is next to a beach.

In order to build a database, for each component (tab), look at the left pane and click Add to add a new component. It will prompt for a name, you can use a descriptive name. When this item is selected in the left pane, the right pane contains the description of that item, that you can edit.

Testing a database
There are several tools used to test the database.

In the Events, you can test the sounds using the button at the bottom.

In the Machines, you can text the current machine by turning it on or off. The Emergency Stop button will stop all machines currently running.

In the Simulator, you can run a database. The database will use the dump as the data, assuming you have it loaded. In order to test a database on a certain environment, you can use Minecraft to get next to a corresponding environment (beach, lake, etc.), and disable MAtmos using F7. Each time MAtmos is disabled, a dump file of the surroundings is created. Please wait about 10 seconds between enabling and disabling MAtmos, otherwise the dumped data could be non-accurate or empty.

To run the database, press the Run button at the left bottom. Note that when the Simulator runs, Instants don't have real-time simulation like you'd expect them to, such as the world clock or the random dices. The moment the data is dumped is a snapshot of the current values MAtmos gathered at that time. You can alter the dump values on the right pane.

The left pane displays the status of each component. There is a left checkbox and a right checkbox. The left checkbox determines if the component is valid. An invalid component is not checked, and should be modified because it means the component can not be simulated, and will bear a default meaningless value. The right checkbox determines if the component is running.

When a simulation runs, it is no use to press the turn on/turn off buttons in the Machines tab as they will be reverted automatically.

Saving a database
You may want to save at a different location. If you have created a database with its own values, you can put that database in the folder matmos_expansions/ to be loaded automatically.

If you have altered a default database, saving it in default_database.xml will not necessarily make it load depending on the options in matmos_options.txt. A new default database is provided with each update (saved in online_database.xmlo), and you don't wish to disable the online updates as it is designed to enhance your experience. You should rarely rely on altering the default database.

The complete MAtmos documentation contains more information as to how databases are loaded.

Ideal sound specifications
This section applies to Minecraft prominently.

In Minecraft the sound files can play in various way depending on how the sound is. It is preferred to use the Ogg Vorbis format for the sounds (.ogg files).

When playing localized sounds, the sound must be mono-channel (no left or right channel).

When playing a global sound or a piece of music, a stereo-channel should be used. A stereo file will play equally balanced no matter what, and a mono file will play in a fake way so that the sound would appear to be equally balanced.

=Complete MAtmos documentation= The following is a complete MAtmos documentation, designed to assist in case the project changes hands eventually, or if you need more information about how it works.

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.

The MAtmos archive provides a default reference file. It corresponds to the latest implementation of MAtmos in Minecraft, and usually between each update, the reference is 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. 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 in the form of expansions. MAtmos will do so right when the main menu loads.

It will load files in this sequence:

Looking at matmos_expansions/ folder, files are loaded when they are found.
 * If it's an ????.xml file, the document structure is loaded into the expansion, and activated when the Sound module is ready to be used.
 * If it's an .xrl file, the URL it contains is fetched from the web. It is therefore put in limbo.
 * If the file is successfully retrieved from the web, the document structure is put into the Expansion, and put out of limbo.
 * If the structure is valid, then the file is written into the disk in matmos_internal/storage/????.xrl.xmlo, then it will be activated when the Sound module is ready to be used.
 * If the structure is invalid, then the file then the following is performed:
 * If the file fails to load of whatever reason (URL is invalid or points to a missing file, or the network is down, or the file is not a valid structure), it is put out of limbo then it loads from matmos_internal/storage/????.xrl.xmlo
 * If that file does not exist, the expansion is put in dummy.

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 (because of the lack of a header).

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. This process starts by default every 1.5 second; this delay can be changed in the options by decreasing the tick span, and will only affect time-critical data. (TODO: check)

The second process is a slow update, which gathers data that is rarely changing or with negligible changes. This process starts every 12.8 seconds.

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 category is itself split into two categories, the time-critical (TC) and the time-relaxed (TR).

Time-critical instants' values are expected change rapidly. Time-critical instants are affected by the custom tick span in the options.

Time-relaxed instants' values are expected charge rarely or at a fixed interval. Time-relaxed instants are unaffected by the custom tick span in the options. There are especially used by the Dice instants in order to keep the probability of an event happening in a fixed interval constant, no matter which value the custom tick span bears.

Every time an Instant value changes, it's counterpart in the Delta sheet is updated in order to hold the delta of that Instant (previous value minus new value).

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 has moved 16 blocks away on the X or Z axis respectively or 8 blocks away on the Y axis, compared to the previously performed Large Scan.

For instance, if the delta of the player current position and the player position on a previously performed Large Scan is respectively 15, 2, and 14 for the X, Y and Z axis, the Large Scan will not perform (even though the actual world distance is greater than 16).

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

Producing sounds
MAtmos Engine outputs data to a generic MAtmos Engine sound manager interface, which is implemented in MAtmos in two versions.

Both versions provide a way to cache sounds and to manage streaming sounds and music using token identifiers. Each time a streaming sound is declared, it is given a token, which is then used to identify a streaming sound to perform actions on.

Generic sound manager and sound system binding
The generic sound manager rewrites and redirect requests towards both the sound manager and the sound system used by Minecraft.

Sound Dampening Mod sound manager and sound system binding
The Sound Dampening Mod (SDM) sound manager rewrites and redirect requests towards the SDM sound system in order to circumvent undesirable effects implied by the use of the generic sound manager and sound system. (TODO: Not implemented yet)

The SDM sound manager overrides the generic sound manager if SDM is detected on the player installation.

How MAtmos Engine works
MAtmos Engine's job is to take the sheets produced by whatever system (In Minecraft case, MAtmos is the system), and compare values in order to produce sounds.

Inside MAtmos Engine, the databases in a loaded form, along with the sheet it requires, form together a Knowledge.

The databases describe components such as Dynamic Values, Conditions, Sets, Machines, Lists and Events.

There are two things a Knowledge performs on runtime. It runs and it updates. When it runs, nothing is evaluated, it produces sounds when it needs to. When it is flagged for update, the Knowledge status will be re-evaluated assuming that the sheets contain fresh information.

During an update, every component status of the Knowledge are updated in this order:
 * Dynamic Values
 * Conditions
 * Sets
 * Machines

The Events results in the execution of a machine, therefore don't require an update.

The mechanism behind MAtmos Engine can be understood by reading the editor tabs in this order.

Event
An Event is the description of a sound event. It contains a list of sounds, a volume random modifier, a pitch random modifier, and a meta modifier.

When an Event is executed, a random sound in the list will be chosen, and that sound will immediately play with a random volume between the minimum and the maximum volume set, a random volume between the minimum and the maximum pitch set, with the meta modifier passed along.

In Minecraft, the meta modifier corresponds to the distance the sounds plays away from the player. The distance will not attenuate the volume of the sound, but serves as a way to make the sound play at a random location around the player at a fixed radius around the player in the X and Z axis, and a random height corresponding to half of that radius on the Z axis relatively to the player altitude.

The meta modifier value zero is a special case, in which the sound will appear to play equally balanced, coming from everywhere regardless of wherever direction the player looks at.

If the maximum of something is less than the minimum of something, that something will behold the minimum value.

List
A List is an array of unique integer constants.

Dynamic Values
The Dynamic Values are database-defined values which consists solely on the sum of several entries of the sheets.

An empty Dynamic Value equals to zero.

Conditions
A Condition holds the boolean result of a comparative expression defined by the value of an unique entry of a certain Sheet, or the value of an unique entry of the Data Values, compared against a constant value with a chosen comparative operation.

Alternatively, the comparative operation can be in or !in, in this case a List is used instead.

A Condition is invalid if the sheet doesn't exist, or if the entry is out of bounds.

Set
A Set is true when all the Conditions in the True list are true therefore making that list suitable, and at the same time all the Conditions in the False list are false therefore making that list suitable.

If one of the lists is empty, that list is considered as suitable.

If a Set references an invalid condition, that condition is considered as false.

A Set is invalid if both lists are empty.

Machine
A Machine is running if any Set in the Power list is true, but if any Set in the Jammer list is true, then it won't be running.

If a Machine references an invalid Set, that set is considered as false.

Time is usually measured with the second, defined by the Operating System ctime.

A Machine can contain several Events, possibly duplicate Events, in which are added additional data that dictates how they are played.

The Event will play the first time the Machine is activated after the Start Delay, and will then run at random intervals between the Minimum Delay and the Maximum Delay, with the volume of that Event modulated with the Volume Modulation value, same with the pitch with the Pitch Modulation value.

The Start Delay value zero is a special case, in which the sound will play for the first time after a random time between zero and the Maximum Delay.

In Minecraft, the maximum produced volume is 1.0, the maximum heard volume is defined by Minecraft sound volume. When a sound will play with a volume v, it will play with a volume of clamp(v*matmos_volume, 0.0, 1.0) * minecraft_volume.

A Machine can contain several Streams. A Stream is an unique file that plays in a streaming fashion.

A Steam will play the file with a volume defined by the Volume Modulation value, same with the Pitch Modulation value. It can Loop if set to do so. It can Pause if set to do so. Only loops can be paused.

In Minecraft, if the Volume Modulation value is zero, MAtmos will consider this sound as being music, to be played with special characteristics.

This Stream will fade in after a certain time when the Machine turns on, defined by Boot Delay, for a duration defined by Fade In duration. If by the time the Machine turns on, the Stream didn't Shutdown yet, it will not fade in. If the Machine turns back off before the Stream Boots, it will not fade in.

This Stream will fade out after a certain time when the Machine turns off, defined by Shutdown Delay, for a duration defined by Fade Out duration. If by the time the Machine turns off, the Stream didn't Boot yet, it will not fade out. If the Machine turns back on before the Stream Shutsdown, it will not fade out.

A Machine is invalid if the Power list is empty, or if an Event doesn't exist (TODO: check).

Development mechanisms
This section is directed towards source code maintainers.

Flag for testing
When a component in the Knowledge is loaded, or at any time its internal composition is modified during runtime, the component is flagged for testing. The next time the component is used, either to get its truth value or to test its truth value, the component is tested to check if it is valid, and then loses its flag for testing.

This ensures that components are secure during usage, and the security tests are not performed when not needed, or repeatedly performed when the component is modified several times at once.

Keyring
When loading a potential malformed database onto an existing Knowledge, a keyring mechanism is put in place in order to revert the changes. The keyring is the index containing all references to the existing components. When a database is about to load, a clone of this keyring is created, containing references to the existing components (which are not duplicated in the process).

The database will load on top of the duplicate keyring. If the loading succeeds, the keyring is applied to the original Knowledge. Otherwise, the Knowledge will reclaim its keyring.

XML
Each component contains an XML method that allows it to write its internal data for save. Updating the UtilityLoader is required every time the internal structure of a component changes.