## What do we want in a tutorial?

Discuss technical or other issues relating to programming the Nintendo Entertainment System, Famicom, or compatible systems.

Moderator: Moderators

tepples
Posts: 22014
Joined: Sun Sep 19, 2004 11:12 pm
Location: NE Indiana, USA (NTSC)
Contact:

### Re: What do we want in a tutorial?

nicklausw wrote:If you're going to teach beginners with ca65, that might as well be a tutorial on its own...(although I suppose config files are the only thing you'd HAVE to comprehend).
That's what I meant by "A later lesson would explain what goes on in nrom128.cfg (linker script)". It'd probably be around when it gets to mappers.
1. What version do you use?
Currently 2.7, but on a forward-oriented tutorial, perhaps switching to 3.4 might be better. In Ubuntu and probably other Debian-based distros, sudo apt-get install python-imaging gives Pillow in the former, and sudo apt-get install python3-imaging gives Pillow in the latter.
2. How to install Pillow on Windows?
Recent versions of Python include pip, for which the procedure is \path\to\pip.exe install Pillow from an elevated Command Prompt.
Pokun wrote:Still if you made it in C++ you could just include a binary for Windows users
But then I'd need regular access to an up-to-date Windows PC on which to test all build procedures in the tutorial. And the user would still need to install a compiler for the Sound chapter in which I teach the reader how to make a lookup table generator.

JRoatch
Formerly 43110
Posts: 390
Joined: Wed Feb 05, 2014 7:01 am
Location: us-east
Contact:

### Re: What do we want in a tutorial?

If I would teach someone with a NES programing tutorial, when I get to the graphics section I would teach it under a CHR-RAM setup first and save CHR-ROM for a more advance side section. CHR-RAM is much more similar to how GPUs of modern, and not so modern, systems where the only thing that's read only is the initial program package. Uploading tile data by $2006 and$2007 also demonstrates more clearly the real separation between CPU and PPU buses.

As for tool dependency issues, the only thing I can think of is to illustrate the native NES data structures, and how the bytes behave with single pixel changes, so that it will be possible for human beings to enter data manually by .db statements or make a tool for themselves, and or point out other options like YY-CHR.

tepples
Posts: 22014
Joined: Sun Sep 19, 2004 11:12 pm
Location: NE Indiana, USA (NTSC)
Contact:

### Re: What do we want in a tutorial?

I've put the outline on a wiki page.

What emulator should we use on each platform? On Windows, FCEUX is probably fine until you get to the raster effects part, at which point you need to buy an EverDrive N8 or PowerPak. On Debian family, I've been using FCEUX (SDL), which Debian packages, for Ctrl+R in my editor and FCEUX (Windows) in Wine for debugging. Fedora doesn't package any console emulators because Red Hat fears Nintendo's legal department. OS X native emulators tend to rely on a payware "Emulator Enhancer" plug-in for half their features.

And which text editor? I use gedit 2 on Xubuntu 14.04 (a Debian derivative), but gedit 3's "new face" without a menu bar scares me. I'd prefer not to depend on Vim or Emacs because each of those editors differs from mainstream desktop UI conventions so much that it would need a separate full-fledged tutorial by itself. In any case, it needs a way to easily run a program from within the editor (the Ctrl+R binding).

Finally, I've never been entirely sure about the copyright license of NESdev Wiki. Otherwise, we'll need to build this tutorial on a wiki with a well-defined license, such as my own wiki which is CC-BY.

Pokun
Posts: 1485
Joined: Tue May 28, 2013 5:49 am
Location: Hokkaido, Japan

### Re: What do we want in a tutorial?

For text editors I liked KDEvelop (although it's more of an IDE). For Windows I'd use Notepad++ (I have highlighting file for 6502). It has a standard plugin that can execute external programs when pressing F6.
43110 wrote:If I would teach someone with a NES programing tutorial, when I get to the graphics section I would teach it under a CHR-RAM setup first and save CHR-ROM for a more advance side section. CHR-RAM is much more similar to how GPUs of modern, and not so modern, systems where the only thing that's read only is the initial program package. Uploading tile data by $2006 and$2007 also demonstrates more clearly the real separation between CPU and PPU buses.
What's so advanced with CHR-ROM? It's super straightforward. CHR-RAM on the other hand requires a mapper which should come in a later chapter. I don't think teaching things out of order is a very good idea.
tepples wrote:
nicklausw wrote:
Pokun wrote:Still if you made it in C++ you could just include a binary for Windows users
But then I'd need regular access to an up-to-date Windows PC on which to test all build procedures in the tutorial. And the user would still need to install a compiler for the Sound chapter in which I teach the reader how to make a lookup table generator.
Why is that? I don't see the difference between the CHR conversion tool and other tools like the assembler. Wouldn't you need to do that anyway in that case?
But if you are using other Python scripts you might as well go with Python from the beginning.

JRoatch
Formerly 43110
Posts: 390
Joined: Wed Feb 05, 2014 7:01 am
Location: us-east
Contact:

### Re: What do we want in a tutorial?

Pokun wrote:What's so advanced with CHR-ROM? It's super straightforward. CHR-RAM on the other hand requires a mapper which should come in a later chapter. I don't think teaching things out of order is a very good idea.
NES development was once new to me, and I can tell you the single most surprising unintuitive thing to me was the CHR-ROM, both that the tile gfx was fixed in rom, and that the data has to be included after the end CPU vectors. That second point is especially important when working with a flat file as it has caused confusion in the past.

Learning CHR-RAM before CHR-ROM may seem out of order historically because CHR-ROM games came first, but I argue that CHR-RAM first is natural, not only because of the possible confusion, but because it can follow the lesson about uploading nametable bytes via the same PPU ports. CHR-ROM can then come later as a precursor to CHR page switching for faster animation.
tepples wrote:And which text editor?
If ubuntu includes gedit by default, recommend it. If not, consider recommending it anyway. gedit has not lost functionality through it's face lift. As long as it's not wordpad or libreoffice, and is a plain text editor, it should be fine.

tepples
Posts: 22014
Joined: Sun Sep 19, 2004 11:12 pm
Location: NE Indiana, USA (NTSC)
Contact:

### Re: What do we want in a tutorial?

43110 wrote:As for tool dependency issues, the only thing I can think of is to [...] enter data manually by .db statements
Note to self: 43110 likes to trace the holes.

Before the MArtist rant in ''The New Tetris'', there was the Y.S. rant in the Famicom cassette version of ''Pachi Com''.
In [i]Pachi Com[/i], Y.S. wrote:Does company N develop with company I's PROS80? I'm AMAZED they can make stuff on that weird (3″ floppy disk) machine! Do they 'trace the holes' when drawing art, too? If you're sick of tracing holes, I'll sell Bear's art machine (ROM) and debugger for \$40 grand... [phone omitted] That's cheap if you want pretty art!!!
("Tracing holes" means programming graphic data directly without the use of any artist tools.)

But anyway, I've slotted in a chapter that explains CHR RAM, tile data formats, and the tile converter tool. I'm just trying not to front-load the exposition too much.
43110 wrote:both that the tile gfx was fixed in rom, and that the data has to be included after the end CPU vectors.
ld65 allows specifying segment contents in any order in the .s files, so long as memory areas are in the correct order in the linker script. An NROM-128 linker script would automatically place CHR ROM contents after PRG ROM, just as it places the header before PRG ROM.
43110 wrote:I argue that CHR-RAM first is natural, not only because of the possible confusion, but because it can follow the lesson about uploading nametable bytes via the same PPU ports.
In my opinion, CHR ROM improves pacing. Copying a full alphabet from PRG ROM into CHR RAM requires use of the (d),Y addressing mode because the alphabet is more than 16 letters long, and 16 tiles is the limit of a,X or a,Y. This in turn would move the introduction of (d),Y addressing mode forward to the start of chapter 2, when I had hoped to introduce it midway through. Or should I include filling CHR RAM in libstufftobeexplainedlater the way I am doing for the iNES header, reading the controller, and clearing OAM?
43110 wrote:gedit has not lost functionality through it's face lift.
If we recommend both pre- and post-facelift gedit, we'll have to walk the user through configuring Ctrl+R in both pre- and post-facelift gedit depending on what apt-get decides to give him.

mikaelmoizt
Posts: 120
Joined: Sat Apr 12, 2014 12:11 pm
Location: Gothenburg, Sweden

### Re: What do we want in a tutorial?

Now for my post that took like 6 hours to write, because I had a hard time conveying that I am really VERY positive to this, and I just want to help out in some way by giving some ideas. Also, swedish is my 'modersmål' so it is pretty hard sometimes to express exactly what I intend to.

I think this is the start of a great initiative! I for one would have loved this back in mid 2013 staring at a grey/gray screen

What comes to mind is the professional aspect of this setup. I don't have anything against the setup nor the 'tools' themselves. In fact, this approach could be the very defacto standard of comming NES dev. The answer to: how do I make my own NES game? to keep it simple. Well, you do this.

A lot of folks here use ca65. I can't complain since I never had the time nor patience to actually try it out for myself.
It would really be easier to help people if every piece of code and tool "worked the same" for everyone. It is a neat idea.

However, for a lot of people starting from pretty much nothing - not all of them, the intimidation factor of having to install, script and configure "this" and "that" in order to get "that and this" to work is what might keep them from even starting.
Yes, sooner or later you will have to do this anyway in some form.

Even though most of us don't see a problem with a bit of configuration, I can see why newbies would prefer to "drag and drop" instead of having all this setup for some 8 pixel sprite on a background that 'doesn't even stomp Goombas'. I was one of them.

"I need to do all that?? Nah screw that, here is something much simpler.."

And that might be the reason why many eventually come to this forum with NN based tutorial code for NESASM3 asking for help.
Don't get me wrong, we (as a community) need the best, most experienced and talanted people to make a once and for all tutorial as good as the wiki, in a 'real life situation' whereto people can look for reference.

But now, that will also require the reader to adapt to a more complex set of tools in order to get started.
I really like my ASM6. I know it may not be as advanced as ca65+stuff, but I haven't yet found anything I can't do with it. As long as I can't find a reason to change, why do it? The png to chr converter (?) sure would be sweet though..

Anyway.. So maybe there could be... 2 or 3 different options for the newcommer to start with in order to adjust to their taste? Anyone want/able to translate the tutorial code from one assembler to another to keep every bit of choice there could be?

Just some thoughts.

Like I wrote, it is hard for me to type in english exactly how I mean, but I hope my opinion is of any use.
I´ve got %01100011 problems but the BITs aint one.

JRoatch
Formerly 43110
Posts: 390
Joined: Wed Feb 05, 2014 7:01 am
Location: us-east
Contact:

### Re: What do we want in a tutorial?

tepples wrote:
43110 wrote:As for tool dependency issues, the only thing I can think of is to [...] enter data manually by .db statements
Note to self: 43110 likes to trace the holes.
100% true. It's why I love understanding file format definitions, and that this was never finished.
tepples wrote:In my opinion, CHR ROM improves pacing...
I agree it would be a bit much to explain in the Hello World chapter, since the point there is showing the shortest path to displaying a word on screen. Since for that chapter you'll most likely be providing the CHR page and skimming over all the assembly details, it would not matter if it's CHR-RAM or CHR-ROM. CHR-RAM with a unexplained upload routine has the benefit of keeping the cart setup the same all the way to the part where 16-bit indexing is explained, but either choice is fine.

About gedit, I guess I never got used to using a hot key for compiling, so I failed to see it missing. I don't know what further to say about choice of text editor.

Also before I start editing your outline or anything, Nerdy Nights has been often praised for it's sound and music engine tutorials. Would taking it's outline be a good start for the sound and music sections?

dougeff
Posts: 2707
Joined: Fri May 08, 2015 7:17 pm
Location: DIGDUG
Contact:

### Re: What do we want in a tutorial?

Re:Sound and music

I would like to see a tutorial explain how to go from a DAW to produce a MIDI, to Famitracker, to exporting data, to incorporating into an actual NES game. I've never seen such a step-by-step beginning to end music tutorial. And ca65 seems like the best choice. I would nominate Rainwarrior for writing that one.
nesdoug.com -- blog/tutorial on programming for the NES

tepples
Posts: 22014
Joined: Sun Sep 19, 2004 11:12 pm
Location: NE Indiana, USA (NTSC)
Contact:

### Re: What do we want in a tutorial?

dougeff wrote:I would like to see a tutorial explain how to go from a DAW to produce a MIDI, to Famitracker, to exporting data, to incorporating into an actual NES game.
Once it's in FamiTracker, the manual for Shiru's FamiTone takes it the rest of the way. But I myself would need a tutorial to get from zero to MIDI. Which free DAW should I use for this tutorial?

One problem with authoring NES music directly in MIDI is that NES music engines tend to prefer repeated phrases/patterns to save space. Listen to the music from WORLD 1-1 in Super Mario Bros. or the bass line in the song that few Silver Surfer players had heard all the way through before NSFs. I'm not sure if MIDI supports any analogous construct.

dougeff
Posts: 2707
Joined: Fri May 08, 2015 7:17 pm
Location: DIGDUG
Contact:

### Re: What do we want in a tutorial?

Perhaps you could export the Treble and Bass line separately, as 2 separate MIDI file. Import them separately, and loop the Bass. And, I'm not sure that there are any good free/open DAWs out there. I have 2 that were fairly expensive, and 1 that came with a Computer Music magazine. I thought, maybe, you could have a more advanced tutorial than Nerdy Nights.
nesdoug.com -- blog/tutorial on programming for the NES

rainwarrior
Posts: 7822
Joined: Sun Jan 22, 2012 12:03 pm
Contact:

### Re: What do we want in a tutorial?

tepples wrote:One problem with authoring NES music directly in MIDI is that NES music engines tend to prefer repeated phrases/patterns to save space. ... I'm not sure if MIDI supports any analogous construct.
MIDI files can be annotated with events, but it can also be practical to detect loops during export. 4klang does this already with MIDI. (I suppose some forms of LZ compression are generic forms of loop detection?)

If it's your own exporter, you can create whatever method for identifying loops/repeats that works for you. In my own engine the exporter automatically detects patterns/instruments/macros that are the same and merges them. The pattern order is rebuilt based on unique data, rather than just using what Famitracker gives. I prefer to do it this way than try to optimize within Famitracker, because it makes it easier to split shared ones later.

Startropics has a really cute music data format. Each track has up to 256 bytes per channel, and there are loop/repeat command codes. It's nice and compact, though it limits song length/complexity quite a bit.

Also, why would you want to use anything besides Famitracker to make your NES music? (Or even PPMCK / Muse / Deflemask.) These things already give a great 1:1 NES composition experience, why do you want to use a generic format like MIDI?

A lot of people seem to have good luck with shiru's Famitone too. It's one of the only "drop in" solutions that this homebrew community has.

dougeff
Posts: 2707
Joined: Fri May 08, 2015 7:17 pm
Location: DIGDUG
Contact:

### Re: What do we want in a tutorial?

why do you want to use a generic format like MIDI?
I don't use MIDI this way, currently. But, the DAW interfaces are so much better than the Famitracker interface. I can record direct from a MIDI keyboard into a DAW and edit the notes directly and easily.
nesdoug.com -- blog/tutorial on programming for the NES

rainwarrior
Posts: 7822
Joined: Sun Jan 22, 2012 12:03 pm
Contact:

### Re: What do we want in a tutorial?

Famitracker actually has MIDI input support, if you want to use a MIDI keyboard to enter notes into it.

dougeff
Posts: 2707
Joined: Fri May 08, 2015 7:17 pm
Location: DIGDUG
Contact:

### Re: What do we want in a tutorial?

Oh. I can't know everything.

Well, that sort of proves my original point. A new tutorial should show how to do music with Famitracker.
nesdoug.com -- blog/tutorial on programming for the NES