Soundpack format documentation

Soundpacks

In MAtmos, soundpacks are used to define what sounds to play, and when. A soundpack must have an assets/matmos/mat_pack.json file containing meta information.

A soundpack consists of one or more expansions, which are used to group sounds together. The volume of each expansion can be tweaked individually. The list of expansions is defined in assets/matmos/expansions.json. An expansion must have a database, which is a defines when each of its sounds should be played. These use a JSON format.

If you're creating a soundpack, it's highly recommended that you look at existing ones for reference, like Default or Zen.

Expansion database

An expansion database is a JSON object, which can have a field for each of the following components. For example, conditions go in the condition field of the object, sets go in the set field, and so on, like this:

{
  "condition": {
    "Nearby water": {
      "sheet": "_DYNAMIC",
      "index": "Water (Small)",
      "symbol": "GREATER",
      "value": "4"
    },
    // other conditions...
  },
  "set": {
    // the sets...
  }
}

Conditions

A condition is a condition upon the value of an index in a sheet.

Example

In this example, the condition is true when the value of the Water (small) index in the _DYNAMIC sheet is GREATER than 4.

"Nearby water": {
  "sheet": "_DYNAMIC",
  "index": "Water (Small)",
  "symbol": "GREATER",
  "value": "4"
}

Fields

• sheet, index: the sheet and the index the condition is based on. Use the debugger to find the sheet and index you need.
• symbol: can be one of ALWAYS_FALSE, ALWAYS_TRUE, EQUAL, NOT_EQUAL, GREATER, LESSER, GREATER_OR_EQUAL, LESSER_OR_EQUAL, IN_LIST, NOT_IN_LIST.
• value: the value which is the basis for comparison

Sets

A set collects the value of multiple conditions into one value.

Example

"Nearby water": {
  "yes": [
    "Nearby water"
  ],
  "no": []
},

Fields

• yes: all conditions in this list must be active for the set to be active
• no: none of the conditions in this list must be active for the set to be active

Machines

Machines are responsible for playing sounds. When a machine is active, the sound associated to it will play. The associated sound can be an event (a one-shot sound) or a stream (a longer sound that can loop).

Example (with event)

"Small amounts of water, outdoor": {
  "allow": [
	"Nearby water"
  ],
  "restrict": [
	"Abundant water",
	"Incave",
	"Indoor"
  ],
  "fadein": 0.0,
  "fadeout": 0.0,
  "delay_fadein": 0.0,
  "delay_fadeout": 0.0,
  "event": [
	{
	  "event": "Lake",
	  "vol_mod": 0.3,
	  "pitch_mod": 1.0,
	  "delay_min": 6.0,
	  "delay_max": 6.0,
	  "delay_start": 3.0
	}
  ]
},

Example (with stream)

"Rain outdoors": {
  "allow": [
	"Rain outdoors"
  ],
  "restrict": [
	"Keep vanilla rain"
  ],
  "fadein": 2.0,
  "fadeout": 2.0,
  "stream": {
	"path": "matmos_hl/loop/rain.ogg",
	"vol": 0.2,
	"pitch": 1.0,
	"looping": true,
	"pause": false
  }
},

Fields

• allow: all sets in this list must be active for the machine to be active
• restrict: none of the sets in this list must be active for the machine to be active
• fadein: the time in seconds it takes for the machine to reach full volume after the fadein delay
• fadeout: the time in seconds it takes for the machine to reach 0 volume after the fadeout delay
• delay_fadein: the time in seconds it takes for the machine to start fading in after being activated
• delay_fadeout: the time in seconds it takes for the machine to start fading out after being deactivated
• event: the event the machine plays when active
  • event: the event's name
  • vol_mod: the event's volume will be multiplied by this value
  • pitch_mod: the event's pitch will be multiplied by this value
  • delay_min: ???
  • delay_max: ???
  • delay_start: ???
• stream: the stream the machine plays when active
  • path: the path to the stream. It must be defined in sounds.json.
  • vol: the volume of the stream
  • pitch: the pitch of the stream
  • looping: if true, the stream will restart after it finishes playing
  • pause: ???
• event_pair: use this instead of event if you want a pair of events with an indoors and an outdoors variation
  • outdoor: an event object that will play if the player is outdoors
  • indoor: an event object that will play if the player is indoors
• stream_pair: use this instead of stream if you want a pair of streams with an indoors and an outdoors variation
  • outdoor: a stream object that will play if the player is outdoors
  • indoor: a stream object that will play if the player is indoors

Events

An event is a one-shot sound.

Example

"Lake": {
  "vol_min": 0.5,
  "vol_max": 1.0,
  "pitch_min": 0.9,
  "pitch_max": 1.3,
  "distance": 0,
  "path": [
	"matmos_hl/water/lake1.ogg",
	"matmos_hl/water/lake2.ogg",
	"matmos_hl/water/lake3.ogg"
  ]
},

Fields

• vol_min, vol_max: each time the sound plays, its volume will be randomly chosen in this range
• pitch_min, pitch_max: each time the sound plays, its pitch will be randomly chosen in this range
• distance: ??? (the sound's distance from the player?)
• path: each time the sound plays, it will be randomly chosen from this list. These must be defined in sounds.json.

Dynamic

Collections of (sheet, index) pairs can be defined here, which can be used as a single value to base conditions on. These will appear in the _DYNAMIC sheet.

Example

"Glass (Small)": {
  "entries": [
	{
	  "sheet": "scan_small",
	  "index": "minecraft:glass_pane"
	},
	{
	  "sheet": "scan_small",
	  "index": "minecraft:glass"
	}
  ]
},