`crystal.py` parses the ROM into classes and objects. It prmarily parses map headers, "second" map headers, map event headers, map script headers, map triggers, map "callbacks", map blockdata, xy triggers, warps, people-events, texts and scripts. The purpose of the file is to parse the ROM into python and then spit it back out with the global `to_asm()` method.
Note: throughout these examples it is possible to use `reload(crystal)` instead of `import crystal`. Once the module is loaded a first time, it must be reloaded if the file changes and the updates are desired.
After running those lines, `cp extras/output.txt main.asm` and run `git diff main.asm` to confirm that changes to `main.asm` have occurred. To test whether or not the newly inserted ASM compiles into the same ROM, use: `make clean && make`. This will complain very loudly if something is broken.
Here is a demo of how to investigate a particular script, starting with only an address to a known script (0x58043). In this case, the script calls the `2writetext` command to show some dialog. This dialog will be shown at the end of the example.
```python
import crystal
# parse the script at 0x58043 from the map event header at 0x584c3
# from the second map header at 0x958b8
# from the map header at 0x941ae
# for "Ruins of Alph Outside" (map_group=3 map_id=0x16)
script = Script(0x58043)
# show the script
print script.to_asm()
# what labels does it refer to?
# these must be present in the final asm file for rgbasm to compile the file
assert definition_param_count == current_param_count, "this should never " + \
"happen: instance of a command has more parameters than the " + \
"definition of the command allows"
# get the first parameter (the text pointer)
param = params[0]
print param
# <crystal.RawTextPointerLabelParam instance at 0x8ad4b0c>
# RawTextPointerLabelParam instances point to their text
text = param.text
print text
# <crystal.TextScript instance at 0x8ad47ec>
# now investigate this text appearing in this script in "Ruins of Alph Outside"
print text.to_asm()
```
The final output will be the following text.
```asm
db $0, "Hm? That's a #-", $4f
db "DEX, isn't it?", $55
; ...
```
However, this is not how that `TextScript` object would appear in the final ASM. To see how it would appear in `main.asm` once inserted, you would run `print crystal.to_asm(text)` to get the following.
#### Figuring out where a script appears based on a known address
Another approach is to parse the entire ROM, then check a script at a particular address. This has the advantage that the script object will have the `map_group` and `map_id` variables set.
```python
import crystal
# parse the ROM
crystal.run_main()
# get the parsed script
script = crystal.script_parse_table[0x58043]
# read its attributes to figure out map group / map id
map_group = script.map_group
map_id = script.map_id
# MapHeader is not given all the info yet
# in the mean time "map_names" contains some metadata
"OAK: Aha! So\nyou're !\nI'm OAK! A #MON\nresearcher.\nI was just visit-\ning my old friend\nMR.#MON.\nI heard you were\nrunning an errand\nfor PROF.ELM, so I\nwaited here.\nOh! What's this?\nA rare #MON!\nLet's see\xe2\x80\xa6\nHm, I see!\nI understand why\nPROF.ELM gave you\na #MON for this\nerrand.\nTo researchers\nlike PROF.ELM and\nI, #MON are our\nfriends.\nHe saw that you\nwould treat your\n#MON with love\nand care.\n\xe2\x80\xa6Ah!\nYou seem to be\ndependable.\nHow would you like\nto help me out?\nSee? This is the\nlatest version of\n#DEX.\nIt automatically\nrecords data on\n#MON you've\nseen or caught.\nIt's a hi-tech\nencyclopedia! received\n#DEX!\n"
