Syntax:

incbin "path/to/binary_file"

Or - in combination with DATA:

data varname![] = incbin "path/to/binary_file"

The INCBIN directive instructs the assembler to include a custom binary file. This is useful to include graphics, music or any kind of data - even machine code routines - in your program.

Note: the included file must be a path relative to the folder where the XC=BASIC source is.

Important note: if not using in combination with DATA, you have to be very careful, as the binary stream will be “injected” into the program right at the point where the compiler encounters the directive. Make sure that the included data is outside the program flow (unless it's meant to be there).

An example of wrong usage:

rem program starts here
print "welcome to my buggy game"
incbin "sprites.bin"
print "now let's play"

In the example above, after printing the welcome message, the program will try to execute whatever is in “sprites.bin” which will likely result in a crash. The good practice is to separate your code and data or use a GOTO command to skip unwanted parts of the program.

The above example fixed:

rem program starts here
goto start
incbin "sprites.bin"
start:
	print "welcome to my cool game"
	print "now let's play"
	

Or:

rem program starts here
print "welcome to my cool game"
print "now let's play"
end
incbin "sprites.bin"
	

Although the compiler will let you know the exact addresses where the included files got assembled within the final executable, these addresses may be changing. In most cases you will want to use INCBIN in combination with ORIGIN to make sure that your included binaries are always located at the same address. Another safe and useful usage is in combination with the DATA statement.