Special Process Effect

The Special Process Effects page allows for the import, export, and addition of special processes. While this page cannot edit special processes written in C using c-of-time, it does not have any conflicts with the environment. Requires the ExtractSPCode patch to view, under Patches -> ASM -> Special Process Effects.

What is a special process?

A special process is arbitrary assembly code callable via the script opcode ProcessSpecial. Thus, the "effect" of a special process refers to the underlying assembly code called. While in an unedited ROM, special processes are hardcoded and implemented in a big switch-statement, the ExtractSPCode patch extracts their code into the file BALANCE/process.bin, which allows for simple importing and exporting.

Special processes are used for a variety of specific tasks that script opcodes weren't designed for, such as:

• Manipulating the active party
• Forcing the game to go to the Top Menu
• Counting the number of a certain item in the bag

And much more! Since special processes allow for the import of arbitrary assembly code, you can essentially do anything within the confines of Ground Mode (i.e., you cannot call Dungeon Mode code from a special process).

Tabs

Special Process Effects Tab

A table listing out all special process IDs and their corresponding effects.

• ID: A number indicating special process, i.e., the first parameter of the script opcode ProcessSpecial.
• Effect: A number indicating effect, i.e., the value used to obtain arbitrary assembly code stored in the file BALANCE/process.bin.
  • Double-clicking this value allows it to be changed. Attempting to input an invalid value will revert the change.
  • Each value in this column corresponds directly with Effect IDs in the Effects Code Tab.

Clicking the Go To button will switch the view to the Effects Code Tab, focusing on the effect on the highlighted row.

Clicking the Add Special Process button will add a new valid ID for a special process, but not add an additional effect. Adding and importing a new special process effect must be added in the Effects Code Tab.

Effects Code Tab

A section allowing for the import, export, addition, and deletion of special process effects. The Used By section only displays the special process ID mapped to the highlighted effect and cannot be edited in this view. Changing which special process maps to which effect must be done in the Special Process Effects Tab.

• Add (+): Adds a new special process effect.
• Delete (-): Deletes a special process effect; you may only delete an effect that is not mapped to any special process ID.
• Effect ID: A drop-down menu listing all special process effects. Clicking one will update the view accordingly.
• Import Code: Modifies the current effect from a file. The file used can be one of the following:
  • Assembly code written in plaintext (typically with the .asm extension); this will be fed into ARMIPS for compilation, and if successful, will modify the effect.
  • A raw binary.
• Export Code: Exports the current effect to a new file. The resulting file is a raw binary, NOT a disassembled text representation of assembly! Viewing a disassembly requires the use of an external tool, such as Ghidra, Capstone Engine, or a simple "Hex to ASM" website.
• Clipboard Import: A textbox field only meant for clipboard content pasting. Clipboard content pasted here will be fed into ARMIPS for compilation, and if successful, will modify the current effect in the same way the Import Code button does.
• Effects Library: Redirects to a GitHub repository meant to act as a library for writing custom special process effects. Mostly deprecated, as far more information on the game's functions can be found on pmdsky-debug.
• ASM Editor: Redirects to a deprecated code editor GUI for writing custom special process effects.

Writing custom special processes

A special process importable via the Special Process Effects tab must be written in ARMv5 assembly, which will be compiled by ARMIPS.

Keep in mind that the maximum number of bytes a special process can contain is 0x810; each instruction is 0x4 bytes.

Register Context

Special processes execute under a very specific register context; when run, certain registers always represent certain values.

Special Process Register Context

Register	Purpose	Comment
r0	Return value of a special process; can be checked in a script switch-statement.	A negative value will cause the special process to run again.
r4	Pointer to the main routine's script_routine_state structure.	For more info, see pmdsky-debug's Ground Mode headers.
r5	ID of the executing special process.
r6	Second parameter of the executing special process.
r7	First parameter of the executing special process.

Additionally, the standard ARMv5 caller-callee convention still applies to special processes. The values of registers r4-r11 and r13 must remain the same when your custom code begins and ends.

Code Template

Using the below template for writing custom special processes is highly recommended!

; ------------------------------------------------------------------------------
; A template to code your own special process effects!
; ------------------------------------------------------------------------------


.relativeinclude on
.nds
.arm


.definelabel MaxSize, 0x810

; Uncomment the correct ".definelabel" lines based on your target region.
; Comments begin with ";", like this line!

; Note: Lines including the "standard library" files aren't strictly required,
; as they simply add labels for a handful of functions. For more info on
; the game's functions and types, see pmdsky-debug!

; For US
;.include "lib/stdlib_us.asm"
;.definelabel ProcStartAddress, 0x022E7248
;.definelabel ProcJumpAddress, 0x022E7AC0

; For EU
;.include "lib/stdlib_eu.asm"
;.definelabel ProcStartAddress, 0x022E7B88
;.definelabel ProcJumpAddress, 0x022E8400

; For JP
;.definelabel ProcStartAddress, 0x022E887C
;.definelabel ProcJumpAddress, 0x022E90F4


.create "./code_out.bin", ProcStartAddress ; MUST change "ProcStartAddress" on this line to be the raw hex value of your region!
	.org ProcStartAddress
	.area MaxSize
		; Your code here!
		
		; Always branch at the end!
		b ProcJumpAddress
		.pool
	.endarea
.close