Thread: [Tutorial] The Guide To NSE
View Single Post
Old July 28th, 2010 (11:21 AM). Edited August 19th, 2010 by link12552.
link12552's Avatar
link12552 link12552 is offline
to measure how far we wonder
Join Date: Dec 2007
Location: The blue one
Age: 20
Gender: Male
Nature: Calm
Posts: 203

The Guide to NSE
by: Link12552

NSE is a powerful tool used to edit practically any image in your Pokemon GBA game.

Latest version:
Download in the NSE Thread attachments

  • Basic understanding
  • Drawing
  • Imports and Exports
  • Palette Editing
  • Resizing a sprite
  • Adding / Removing frames
  • Re-pointing
  • Advanced Mode
  • Offset browsing
  • Lz compressed images
  • The Hex Editor
  • Bookmarks pt1
  • Bookmarks pt2
  • Settings.ini
  • Writing your first plug-in, commands

Basic Understanding:
NSE consists of many components used to make editing your sprites easier and more intuitive. These components are laid out in groups (Game information, sprite navigator, info...)

Loading a sprite:
NSE has a few different ways to load a sprite depending on the information you provide information. The basic way to navigate through sprites is by using the sprite navigator. Toggle back and forth on both palette and frame or enter numbers and simply press the go button.

After you've loaded a sprite, a red square will show up in the top left hand corner of the image, this square reflects the area you are currently editing in the Canvas and can be moved simply by clicking the area of the image where you want to draw. The canvas is where the drawing is done. Clicking on the canvas will draw the color you currently have selected. Colors can be selected by selecting the from the palette or by Right-Clicking on any color in the canvas.

Imports and Exports:
After you loaded an image in NSE, you may decide that you want to edit it in one of your favorite drawing programs like MS paint or Photoshop. This can be done by selecting Export & Export Bitmap in the File menu.
After you've drawn your sprite your going to want to get it back in the game. To import an image go to the File menu and select Import & Import bitmap. You may the n chose to import only the image, the palette, or both.

Notice: Some versions of MS paint have been shown to corrupt 16 color bitmap palettes.

Another method of importing and exporting sprites is to use a NSL File (Nameless Sprite Library). An NSL file stores all the same information as multiple bitmaps plus more, and can easily be edited in the NSL editor (Included with the NSE download).
Exporting an NSL version of your sprite can be done by going to the File menu and selecting Export & Export Sprite Library.
Importing an NSL is done by going to the File menu and selecting Import & Import Sprite Library.

Palette Editing:
Palettes are the colors that a sprite uses. When in regular OW sprite editing the palette can be changed to any available in your game by changing the number labeled "Palette:" in the "Info: Header" group and pressing the change button. To see what palettes are available in your game's palette table type "FF" in the Palette box and press the change button (Unless your game uses palette FF).

While changing palettes is good, you may want to completely change the colors that a sprite uses. This can be done by selecting the Edit menu and selecting Palette. Unless the sprite you're viewing is being displayed in Gray-Scale or it's palette protected, the Palette Editing dialog will appear.
Using the dialog consists of entering the color code manually, clicking on the color you want to change and picking it from the color selection dialog, or clicking the eye dropper, holding the left mouse button down, and picking the color from any where on the screen. To use a selected color, click the textbox above the color you want to change, then click the color next to the eyedropper.
Palettes may also be imported, as part of a 16-color bitmap or a NSL file.

Resizing a Sprite:
One of the features in NSE is the ability to resize sprite OW's. This is done in the Preferences dialog that is accessed in the Edit menu. When editing the size of a sprite it is important that you switch from "Index" to "All" mode; this way you're editing all the frames of a sprite. Next enter the height and width you wish to change to (Have to be multiples of 8 <= 248) and click save. NSE will then change all of the variables required to change size, and re-point all of the frames to consecutive free space.

Note: If the Preferences button is "grayed out" it means that the sprite you're viewing doesn't have any preferences or editing their preferences could possibly wreck the sprite.

Adding / Removing Frames:
Another feature in NSE is the ability to change the amount of frames a sprite uses. Open up the preferences window and switch the top tab from primary to secondary mode. At the bottom you will see the Change Frames group. The amount of frames presented here is +1 the amount you will see when navigating because we count frame zero. If you don't want to copy the old frames over to the new ones (a.k.a you want a fresh sprite) uncheck "Copy Frames." When your done, click change and NSE will re-point the sprite's Frame Table to free space.

Note: to keep track of how many frames a sprite uses after you've changed the amount, NSE inserts a byte at the end of the Palette Registers data in the sprite index.

When an image, data table, or really anything gets to big for it's spot in the game, it has to be moved to a new location. This is common ground in NSE, things are going to be re-pointed, although NSE does its best to avoid having to re-point unless necessary. Any place where you see a textbox with a magnifying glass next to it, typically means that something is going to be re-pointed. In most cases, unless a pointer needs to fulfill a certain requirement or you chose to custom re-point, you aren't going to have to do anything because NSE will re-point for you and in most cases, tell you what it's re-pointing and to where. In other cases you will have to provide the pointer. Either find it yourself in a hex editor or a program like FSF, or just click the magnifying glass.

Advanced Mode:
NSE has two ways it will display itself and function. There's basic mode which is good for standard editing and then there's advanced mode. Advanced mode can be accessed from the Options menu or by pressing Ctrl- M. Advanced mode adds a number of functions to NSE.

Boundaries: Boundaries are the things that say "there are only 151 sprites in this game", "this sprite has only 8 frames", or "The palettes that exist in this table are..." In advanced mode, you can turn these off.

Input: When doing things like re-pointing certain images and palettes, instead of NSE finding a free space, you can input your own you can also tell NSE not to re-point all references to the image your saving

Display: While in Advanced mode, much more information about the sprite you're viewing is displayed. Information regarding how the sprite is formatted, animated, located in the game, ect.

Offset Browsing:
A defining feature of NSE is its offset browsing capabilities. If you know an images offsets you can display and edit it. Offset browsing is pretty straight forward. Open the offset browsing dialog by going to the View menu and selecting Offset. The image and palette offsets are typed in the designated boxes and then the size is provided. NSE can display an image in grayscale mode if you don't know the palette offset. Sizes must be multiples of eight and width * height <= 16384

LZ Compressed Images:
An average game will contain thousands of images, so in order to keep file size down, a great potion of images are compressed. If an image is compressed it can be gotten to the same way as an uncompressed image (from the offset browser). NSE knows if something is compressed and will adjust as needed. LZ compressed data is size dependent, so if a saved image is too big for it's old location, it has to re-pointed. This can be done manually in Advanced mode or NSE can handle it.

Note: NSE also supports compressed palette editing and re-pointing.

The HEX Editor:
NSE features its own built in Hex editor. Although very simple, it can easily get most small jobs done. The hex editor has a few predefined offsets that change to the current sprite and a small note area. The built in hex editor is best for small adjustments and, because of its basic nature, is incredibly fast.

Bookmarks pt1:
Because it's nearly impossible to remember every offset for every interesting image you ever encounter, NSE has its own book-marking system built in, accessed by going to the Options menu selecting Bookmarks & View Bookmarks. If you come across an image you think is interesting, book-marking it, is as simple as selecting Bookmark this offset. Bookmarks can store compressed images as well as uncompressed images and store all the necessary information for viewing an image in a desired way. Even a basic grouping system is implemented within the book-marking system. Editing your bookmarks can be done by switching to the Edit tab in the bookmark window. Bookmarks are all stored in a single file located in the same folder as NSE. To open a bookmarked image simply select it and click the open button, simple.

Notice: Bookmarks that have palette editing disabled, quite simply put, may not have their palettes edited.

Bookmarks pt2:
The book-marking engine is very powerful, but because of its potential all of the options are not fully accessible through the Edit tab. The bookmark file "bookmarks.nbm" can be edited in programs like notepad. A basic file may look like this:

  'Comment about boats
  Boat: &H469FD8,&H46A6d8,040038,Image,Palette
  Waves: &H46A6F8,&H46A6D8,020080,Image,Palette
  Egg Hatch: &H25F862,&H25F842,020088,Image,Palette
Header: enclosed in [xxxx], this defines what game (XXXX) the bookmarks are for.
Folder: defined by <y>, this defines a folder named (Y)
-both the header and folders are closed by a slashed version

Bookmark composed as:
Name : Image offset , Palette Offset or grayscale, Size Hex (wwwhhh) , Editing mode
ex. Flowers: &H376D84,&HE94350,010030,Image,Palette
In certain cases, !x may be used to define the length of bytes to read (X)
ex. Textbox 1: &H41F1C8,&H471DEC,028020,!240,Image,Palette
Dynamic pointers: you can use a X+ y operator to tell NSE to get a pointer from the game.
P+ tells NSE to get the palette tables offset + y
S+ tells NSE to get the original sprite tables offset + y
+ By itself tells NSE to use an OW palette. (There is no y in this case)

ex. Hero 0: &HE69EBC,+0,040040,Image
^ Tells NSE to use the Hero OW palette "0" to draw the image, but the edit mode is set to image so you can't mess up the Hero OW palette.

If you've re-pointed your palette or sprite table you need a way to tell NSE that you've done so. Even when you've changed the game header you need to create a settings.ini file
This is done in a program like notepad and saved as settings.ini in the same directory as NSE.

Inherits: "Original Game header, without quotes"
Palette table = "The start of the sprite palette table, without quotes"
Sprite table = "The stored sprite table pointing to all of the index offsets, without quotes"
Inherits HAS to be included so NSE knows what game it is you're using
  ' If you've just changed the header you can do something like this
  ' Here I've changed my Fire red header to "LINK"
  Inherits: BPRE
  ' Here both the Sprite and Palette table have been moved.
  ' So to tell this to NSE we use "Sprite table =" and "Palette table ="
  Inherits: BPRE
  Sprite table = &H39fdb0
  Palette table = &H1a2400

Writing your first plug-in:
Writing your first (basic) plug-in!
For this you will need an English Pokemon Firered ROM and the latest version of NSE

Before we start I'd just like to tell you what we'll be making,
-It will be a plug-in to display and edit all of the Items in your Firered Rom

And to give you some background,
-all of the item image locations in Firered (English) are stored in a table at &h3D4294
-and their palette locations are stored in a table at &h3D4298
-these tables contain the pointers in consecutive order with a space of 8 bytes in between each pointer
-the pointers are 3 bytes long, but are flipped

Okay, so fire up notepad, or whatever it is your using,
and type this:


This tells NSE that the plug-in is compatible with a game that has the header BPRE (fire red English)
Everything for Firered has to be included in-between these two blocks...

Now were going to add this

We're telling NSE to load the number "8" onto the top of the memory stack

And then this:

Now were telling NSE to multiply whatever is at the top of it's memory (which we assigned the value 8), by I#
-but wait, whats I#...
At the moment NSE begins running our plug-in, it replaces any instance of I# with the current index number in NSE's browser

So currently we have loaded the number 8 into memory, and the multiplied it by the current Index

Next we are going to type this:

This is another math function, but this time it's working with a number in HEX format (hence the number beginning with &h.

Remember (All of the image pointers are stored in a table at &h3D4294 with intervals of 8 bytes in-between them)
Now do you see what were doing, we're adding intervals of 8 bytes based on our Index number.

Now to use what we've accomplished through all that math, type:

Read(mem(0), 3)
Okay a little scary at first, right?
So I'll break it down

Read is a command that tells NSE to read a certain number of bytes from a given location, into its memory
Read is formatted as...
read( the data offset, how many bytes to read)
Here we are telling NSE to read 3 bytes starting at location mem(0)
-but wait another minute, what's mem(0)?
Remember we did all of that math a few moments ago, well all that math was being applied to the top of the memory stack.

So to access the top of the memory stack we use mem(0) .
This tells NSE to use whatever is at depth X (0 in this case) from the memory

So again, we're reading 3 bytes from the location, that is the value, stored at mem(0)
- and we're reading this information on to the top of the memory stack.

Now for an explanation of Flip(3)
Flip, as it's name implies, flips the information stored at the top of memory.
It flips this information in sections of X bytes (3 in this case)

So here should be our code so far:

Read(mem(0), 3)

So far our code is loading a pointer from the item image table into memory, and then flipping it, so that it's usable.

Now to start working on the palette part (the colors)

We are going to again type:

Then we're going to add this

Last time we added the start of the image table, this time we are adding the start of the palette table

And again we will type:

Read(mem(0), 3)
If we ran our plug-in now, it wouldn't appear to do anything...
This is because we've calculated the pointers, but we haven't done anything with them...

This is where the next function comes in,
Type this:

Image(mem(2), mem(0), 00180018)
This command tells NSE to load an image.
the command image is formatted as such:
image( image start-offset, palette start-offset, size)
-but hey what's mem(2) ?
mem(2) refers to a value in memory that has a depth of 2
- but again whats at memory depth 2?

As you add things to the top of the memory stack, things that were once on the top, are now below something...
It's very similar to a stack based memory system

So here is the current memory stack:

mem(3) Append (8), Multiply(I#), Add(&h3D4294)
mem(2) Read(mem(0), 3), Flip(3)
mem(1) Append (8), Multiply(I#), Add(&h3D4298)
mem(0) Read(mem(0), 3), Flip(3)

We want the image offset to equal the pointer we read and flipped from the image table, mem(2)
- and we want the palette offset to be the pointer we read then flipped from the palette table, mem(0)

Now for an explanation of the size, the size format of NSE's plug-in system is an imaginary 4 HEX bytes in length.
- formatted as WWwwHHhh where W is width and H is height
- All the item images are 24 by 24 in size, and the hex version of 24 is 18!
Now were almost done, if you ran the program now it would work, but only untill a certain point...

We need to add this to the very top of our code( so below the [BPRE] ) :

This is telling NSE, that while running our plugin, there are 376 images, and each image has 0 ( so technically 1) frames.
This is done with the imax() and fmax() commands

Your final code should look something like this:

Read(mem(0), 3)

Read(mem(0), 3)

Image(mem(2), mem(0), 00180018) 
Now our plug-in is done!
Save the file as "Items.npi" in the "plugins" folder in the root directory of NSE. (Make sure you're saving in the all files mode/type)

Go ahead, try running it, you should be able to toggle through and edit every item!
Congratulations, now you can begin to harness the full power of NSE!

Questions? Contributions?
Post here.

Reply With Quote