Loops

Set loop point in track: L

This command simply tell where the song loops within a track. At most one occurence of this command should appear in a track.

; play 'c', then loops 'e g b' forever.
A c L e g b

Bracketed loop: [ ~ | ~ ]<num>

Anything between [ and ] will be repeated <num> times. Also, you can specify a split point within the loop with “|” to cut the loop prematurely in the last repetition.

Technical detail: for some reason, this kind of loop unroll its contents, that is, if you write:

; Play c e g 5 times
A [c e g ]5
A [d a f | e]3

it is exactly the same as if you have written this:

; Play c e g 5 times
A c e g c e g c e g c e g c e g 
A d a f e d a f e d a f

This loop is not memory friendly, as you can see, but on the other hand, you can nest bracketed loops without problems.

Multi-repeat loop: |: ~ \ ~ :|<num>

This kind of loop can be used like the bracketed loop above, and like the above you can optionally specify a split point, but with “\”.

Examples:

; Will play "c e g" 4 times
A |: c e g :|4

; Will play "d g b d f a" 3 times, then "d g b"
A |: d g b \ d f a :|4

If you specify more than one split point, the result is quite unpredictable, resulting often in infinite loops, though it compiles fine. Avoid using more than one split point.

Technical detail: Unlike the bracketed loop above, this loop doesn't unroll it contents, it basically puts in the resulting song the segment to repeat, the split point, and the number of times to repeat that segment. Therefore, for large loops and/or high repeat counts, this loop use much less memory in the resulting song than the bracketed loop above. The only shortcomings are 1) they cannot repeat more than 256 times, and 2) they cannot be nested. ppmckc will compile nested loops fine, but NESASM will choke when trying to assemble ppmckc's output, because there will be multiple labels defined with the same name.

Example of failure:

; ppmckc will compile, but then it FAILS in NESASM:
A |:  c e g |: d f a :|4 e g b :|4

example of NESASM output:

NES Assembler (v2.51)

pass 1
#[3]   /tmp/tmpkoUx7l/track.h
   41  01:A008            song_000_00_lp_0000:
       Label multiply defined!
# 1 error(s)
segment usage:

      ZP    $0000-$001F  [  32]
     BSS    $0200-$02F1  [ 242]
                    USED/FREE
BANK   0                               0/8192
BANK   1                               0/8192
                    ---- ----
                       0K   0K

Workaround: for inner loops, bracketed loops will work fine, as always.

; this will work fine
A |:  c e g [d f a]4 e g b :|4
Unless otherwise stated, the content of this page is licensed under GNU Free Documentation License.