
Primary Project Files
=====================

Neccesary files in a project, these are:

[project].nfp - The main project file, containing project data..
layout.cfg - Tells how the NES binary will be structured in segments, and what will be put where.
header.cfg - Configurates the NES header.
prj_declare.asm - Include any user-defined macros or constants here. Just not asm.
prj_rest.asm - Put any code here you want to be done at startup. (just before startup-stadium).
prj_nmi.asm - If you want any code executed in the NMI, put it here.
prj_irq.asm - If you want any code executed in the IRQ, put it here.
prj_zp.asm - Zero Page memory declarations are done here.
prj_mem.asm - Non-Zero Page memory declaration are done here.

Optional Project Files
======================

config.asm - Configurates the common library.
library.cfg - Can be used for configuration of libraries (instead of default configuration).

Folders
=======

\asm - The ASM files generated of Resource files are placed here by NFCompiler.
\bin - The NES binary is placed here.
\generated - Temporarily ASM files CC65 uses to create the NES binary is stored here.
\resource - Resource files are put here.

Feel free to put other stuff in these folders and create other sub-folders. It wont hurt.

NinForge File Format Alikeness
==============================

Resource Files, .nfp and .cfg files share the same concept formats.
When they are read, the Compiler expects a certian type of data, or serie identifiers.
All depending where in the file its reading.

The various types of data:

Tag		!tag;	Identified by '!', with the tag's name following. ';' ends the tag.
				Used when seperating between parts of the file.
Value	00; or $00;	Can be in decimal or hex format. For hex, $ identifies start of the
					value, else any digit from 0-9 identifies the start of a decimal value.
					';' ends the value.
String	"string"	Identified by a " . ends with a " also. Used to give variable-length
				names, among other things.
Braced String		{bstring}		Identifying with '{', ends with '}'. Used for very long
							chunks of text data, where " might be included.
Query	?query;	Seldom used, but identified with a '?', following either yes or no, and ends
				with ';'

Serie identifiers:

Sometimes, the Compiler expects a serie with blocks of data, where the amount of these
are up to the programmer. When a serie is expected, '+' means a new entry follows, and at the
end of that data it will continue to read, until a ';' is placed. It means the end of the serie.

For example, a serie of String-type data could go like:
	+"string1"+"string2"+"string3";

Comments can be placed anywhere in these files between datas, using '/', wich means
both start and end of the comment.

Now onto the actual formats of the files.

Project File Format
===================
Project files are basically composed of Tag type data.
It will continue to read until the tag !eof is found.

Valid tags:
Name				Following		Description
	!name;		"prjname"		Gives the project a name in string-format. Requied.
	!outfile;		"outfname"	Decides the name of the "base" asm-file as string.
							Must include file extension.
	!resource;	+"rname"+..;	Tells which Resource files to include with the project.
							This is seried String data. Do not include file extension.
	!lib;		+"lname"+..;	Tells which Libraries to use in the projects,
							seried String data. Use the ID of the library.
	!config;		"cfgfile"		Any alternate configuration file to use instad of config.asm.
	!info;		{info}		Any public info can be stored here. Braced string.
	!eof;					End of File!

Example of a simple .nfp file:

!name;"My project"
!outfile;"prj.asm"
!resource;+"main";
!lib;+"joypad"+"randomgen";
!info;{This is my project.
This is its info.}
!eof;

Layout.cfg File Format
======================
To begin the config, first you define a segment.
Every segment defines a piece of the ROM by specified size.
(If youve used CC65, the Segment feature of it
is used by the layout configuration. So, its the same concept.)
After defining a segment, you define what will be put in it.
Then you can define more segments.
The file starts out with a seried string, defining the
Segment's name, following three value datas. Format:

	+"segmentname";size;start;fillvalue;

Size - Self-explanary. Size of the segment.
Start - Sets what the assembler's adress-counter will be set to at the start of the segment.
Fillvalue - Specifies a byte value to fill unused space with. Should be $00 or $FF.

Then, follows a sequence of Seried Tags.

Requied tags:

	!header;	Places the NES header as defined by the header configuration.
	!reset;	Places the startup code of the common library.
	!common;	Places the common library ASM (note: rather big)
	!lib;	Places the ASM for all Includable libraries.
	!decl;	Places the Adress-Table for Processes and Stadiums.
	!vector;	Places the vectors for Reset, NMI and IRQ.

Note: Requied tags dont *have to* be placed in the first segment. They have to be placed
in some segment, but only one segment. (!vector can be multiple places, though).

Other tags:

	!res;	"resname"		Places the ASM of specified resource file (no file extension!)
	!asm;	"asmfname"	Places specified file as included ASM.
	!bin;	"binfname"	Places specified file as binary.

When ';' is placed to end reading tags for that segment, you can define more segments
with '+' or you can end the whole layout configuration with ";".

Example of a simple layout configuration:

+"HDR";$10;$0;$0;
	+!header;
	;
+"ROM";$7FFA;$8000;$FF;	/2-page PRG-ROM/
	+!reset;
	+!common;
	+!lib;
	+!decl;
	+!res;"main"
	;
+"VEC";$6;$FFFA;$FF;	/Vectors/
	+!vector;
	;
+"CHR";$2000;$0;$FF;
	+!bin;"gfx.chr"	/place CHR-ROM/
	;
;

Header.cfg File Format
======================
Like the project configuration file, the header config is composed with (unseried) tags.
!eof tells to stop reading file.

Valid tags:
	!prg		prgpages;		Defines number of PRG-ROM banks, with value.
	!chr		chrpages;		Defines number of CHR-ROM banks, with value.
	!mapper	mapperid;		Defines wich mapper is used, with value (Mapper ID)
	!mirr	!h or !v		Defines mirroring type, followed by a tag wich
						is either !h (for Horizontal) or !v (for Vertical).
	!sram	?sram		Toggles sram. Used for defining is a Query-type value.
	!trainer	?trainer		Toggles 512-byte trainer, with Query value.
	!fourscreen	?fscrn	Toggles 4-screen nametables, with Query value.
	!exram	?exram		Toggles Ex-Ram, with Query value
	!eof					-End of File!-

Simple example of a header file:

!prg;4;
!chr;4;
!mapper;4;	/MMC3 Mapper/
!mirr;!h;		/Horizontal Mirroring/
!sram;?yes;	/Battery-packed SRAM is used/
!trainer;?no;
!fourscreen;?no;
!exram;?no;
!eof;

library.cfg File Format
=======================
This optional config file is composed of series
of data. For each serie, a string type data comes
first, determining the name of the library to configure.
After that follows a braced string to replace
the default configuration.

The current way to create a library configuration,
is to look in the \libraries folder of NFCompiler,
find your library, open it in a text editor, find
the "!cfg" tag, and copy the contents of the braced
string following. You can then put it libray.cfg and
redefine the constants.

Simple example of a library configuration file:

+"randomgen"{
lib_random_randomnumbers = 4	;number of unique generated random values you need at the same time
lib_random_integrateinloop = 1	;automatically call random generator?
lib_random_randomity = $30	;minimum calculation cycles. max value = $B0 (increase this if values dont seem random enough)
}
;

Resource File Format
====================
To start resource components, first the resource type has to be defined as a tag.
So, NFCompiler first expects a (unseried) tag.

Valid tags:

	!stadium
	!process
	!routine
	!string
	!constr
	!pal
	!raw
	!eof

Once the resource type has been defined, you can place multiple components
of that type. Serie identifiers are used for each component, where the a following
string defines the component name. The component data follows the name, and once all
component data has been read, you can start new components using the serie
identifiers. (Confused? Looking at the examples later should help.)

As with other files, you should put an !eof tag at the end.

Stadium resource data
---------------------

As mentioned earlier, there at two types of stadium data.
Code, and Process loading data. Therefore, in stadium data you
first need to define wich data to deal with using seried tags:

	+!code	Define code/asm/program/whatever.
	+!proc	Define process loading/unloading data.

Remember that since these are designed as seried datas,
you need to put an serie stop identifier (;) when you have defined both code and proc.

	!code

A braced string follows, containing the stadium code. Simple as that.

	!proc

This is a little more complicated. Process loading contains seried datas as strings,
plus eventual operands. In the strings, to load a process to memory, siply put its
name (without the "process_" forename, the compiler takes care of that.)
To unload a process, put a minus as the first character in the string, then following the
process name. Finally, theres a special character for unloading ALL processes from
memory. Simply put one "!" as the string.

Operands

When, and only when a string for process-loading is put, you can define operands to be
placed in the process' reserved memory -before- its run. A serie identifier is used
to determine whetever operands are used or not. If they are, a value type data follows
determining the number of operands. Then, follows the operands. They are actually put
in a braced string. The braced string is placed directly to a .byte directice without
error checking. So you can place any defined constants, decimal, binary or hexidecimal byte values.
If youre unfamiliar with .byte directives, heres an example of how you can place operand data:
4;{$20,$10,$50,$40} (value before braced string determines #-of-operands)
Following that, you can define more strings for process-loading with serie-identifiers.

Note: The "!" and "-process" strings doesnt use operand data, so it starts directly back
on the string serie sequence after the ".

File Example:

!stadium;

	+"gameinit"

		+!code;{
		ldx	level
		lda	levelpal,x
		jsr	dopal
		ldx	level
		lda	levelscrn,x
		jsr	doscreen
		rts
		}

		+!proc;{
		+"!"+"loop1";+"animation"+2;{$10,5};
		;	/<-- Identifier for No more !code or !proc data in stadium/

	;	/<-- Identifier for No more stadiums/

!eof;

Process resource data
---------------------

Process data is quite simple. For each component, the process
code is placed in one big braced string. Thats all.

File Example:

!process;

	+"animation"{
	incR0
	getR0
	tax
	lda	table1,x
	ldy	table2,x
	jsr	dostuff
	rts
	}

	;

!eof;

Routine resource data
---------------------

See process resource data :)

Note that the routines "resource" name will
become "routine_[name]", so you can either
use that as the JSR label, or you can define your own.

File Example:

!routine;

	+"write4tiles"{

write4tiles:
	asl	A
	asl	A
	tax
	stx	$2007
	inx
	stx	$2007
	inx
	stx	$2007
	inx
	stx	$2007
	rts
	}

	;

!eof;


String block resource data
--------------------------

A string components contains seried datas, one
for each line of text.
For each serie, follows two value type datas,
determining Vertical (Y) and Horizontal (X) coordinate
to start the line of text. Next, is the string itself,
logically in text type data. NFC keeps reading series
until serie end identifier is read.

File Example:

!string;
	+"mainmenu"
	+22;10;"1 player"
	+23;10;"2 player"
	+24;10;"Instructions"
	+25;10;"Credits"
	+26;10;"Password";

	;

!eof

Construction resource data
--------------------------

A construction component contains series of datas, one
for each "line". Since constructions can be either attribute
or nametable-oriented, each serie starts with a tag determining
wich type to use; !tile for nametable data and !attr for attribute data.

	!tile

The serie continues with two value type datas, determinging
Vertical (Y) and Horizontal (X) start coordinate. Next, the
start tile value as a braced string. This will output as part of
a .byte directive, meaning you can use constants and other features
of CC65. Or you can just put for example {$20} to have the start
value to it. Next, is the tile-length of the line as a value type
data. Then, a tag tells to draw either Horizontally (!h) or
Vertically (!v). Then, a tag that can be set to !v to read
"Vertically" from the Pattern Table, i.e. increase tile value
by $10. Anything else in the tag will have the feature off.
Finnaly, three values decide rest of construction data:
Value to increase tile-value by for every tile drawn,
value to increase tile-value by for every 2nd tile drawn,
Value to temporarily add on output tile-value by every Even tile drawn.
All of these three has a max value on 3.

	!attr

Like in !tile mode, the serie continue with two value datas for
Y and X draw start position, just that these (since this is attribute data)
choose 16 pixel-block position. Next, a value determines the palette to
put, then a tag (!h or !v) determingin drawing direction, finnaly,
a value as the length to draw the attribute data.

File Example:

!constr;
	+"logo"
	+!tile;4;8;{chr_logo}16;!h;!h;1;0;0;
	+!tile;5;8;{chr_logo+$10}16;!h;!h;1;0;0;
	+!tile;6;8;{chr_logo+$20}16;!h;!h;1;0;0;
	+!tile;7;8;{chr_logo+$30}16;!h;!h;1;0;0;
	+!attr;2;4;1;!h;8;
	+!attr;3;5;1;!h;8;;

	;

!eof;

Palette resource data
---------------------

As it cant get much difficult, palette resource data is composed of
seried value type data, each value representing a palette color vale.

File Example:

!pal;

	+"sample"
	+$0F;+$2A;+$1A;+$0A;
	+$0F;+$27;+$17;+$07;
	+$0F;+$20;+$10;+$00;;

	;

!eof;

Raw resource data
-----------------


Like palettes, raw resource data is made up of seried value-data.
Just note that each value must be a byte-value, not more.

File Example:

!raw;

	+"data"
	+1;2;3;$22;$67;$FF;;

	;

!eof