1 """
2
3 Meat Engine Mood Music
4
5
6 MeatEngine.MoodMusic is a module for selecting music adaptively based
7 on the mood of the game. It is intended to support multiple players
8 (PyGame, BASS, FMod, OpenAL), but only PyGame's sound system is
9 currently supported.
10
11 Each distinct "state" that the game can be in is called a
12 "mood". Music can be associated with a mood, or with a transition
13 between moods.
14
15 At initialization time, first create an instance of the library
16 wrapper object (currently LibraryPyGame is the only one
17 supported). Then create a player object with the library as an
18 argument.
19
20 You then define the states ("moods") by calling addState on the player
21 object. You may add transitions between states if you plan on using
22 this feature. If you do not want music playing between states, you
23 don't need to set them up.
24
25 Next, assign music to the states and transitions (if any). This can be
26 done a directory at a time with addMusicDirectoryToState and
27 addMusicDirectoryToTransition. There are also methods to add
28 individual files to states or transitions.
29
30 Finally, call setState() to establish the initial state.
31
32 At runtime, call the player's tick() function periodically (once per
33 frame is convenient, but if you call it less frequently, you may get
34 gaps in your transitions). When a song ends, the player checks the
35 current mood and plays an appropriate song.
36
37 Moods can be changed by either calling setState() or pushState(). When
38 calling setState(), you are strictly controlling the mood of the next
39 song (the current song still plays to completion). This may be useful
40 for states that change frequently, more often than the length of a
41 song.
42
43 Alternately, you can use pushState(), and the player will maintain a
44 stack of states. As a song finishes, if the stack is more than one
45 mood deep, the player will see if a transition has been established
46 for those two states, and it will play a song from the list
47 associated with that transtion. When the transition song is finished,
48 the stack is again inspected. If there are still more than one mood
49 deep, another transition is played, until the stack is down to a
50 single mood.
51
52
53
54
55 """
56