My Atari Lynx Programming Journal

[OldAtAtari]

Hello, everybody.

 

Life-long Atari fan here, starting with the 2600 when I was little, then the 7800 about the time when everybody else I knew got Nintendos and Segas. And ever since middle school, the dream was to own a Lynx. And for my 44th birthday last month, I finally got a Lynx. It's a Lynx II, now with new caps, new power circuit, and the 5V USB mod so I can run it off a portable power bank. And when the BennVenn screen mod is in stock, I plan to do that too. Even without the fancy screen, I'm loving the Lynx. It's a relaxing thing to pick up at the end of the workday.

And I also love programming, usually in Perl for work-related things. But now, I want to learn Lynx programming. Free time is hard to find, so this might be a slow process, but I intend to document the process here as I learn it.

 

I'll be asking questions here too, so there should be some responses from experts in this thread. And by the way, I do hope others will post here, both expert and novice,  with their comments, corrections, and questions. I want this to be a topic about learning to program, and any contributions towards that are very welcome.

And, just to let you know, I tend to bounce from hobby to hobby pretty quickly, so this journal might stop abruptly before much real progress is made. But in the meantime, maybe I'll type at least a couple things that help the next person.

Edited August 5, 2020 by OldAtAtari

[OldAtAtari]

Assembly or C? Or both?

 

I've been chatting with a few of you in this forum the past day or two, and I think I've decided on C. Assembly seems more fun (I enjoyed it in college 20-some years ago), but C seems more commonly used and therefore might have more abundant support and documentation. So I'm planning to start in C and then move on from there.

For the conversation about all that, you can look here:
https://atariage.com/forums/topic/256753-atari-lynx-programming-tools-and-tutorials-wip/?do=findComment&comment=4600021

Edited August 5, 2020 by OldAtAtari
Linking conversation regarding Assembly versus C.

[OldAtAtari]

Setting up my environment.

 

*****

UPDATE: Forget these instructions. Too much has changed since then. I've typed up a better procedure here:

https://atariage.com/forums/topic/310195-lynx-programming-environment-setup-routine/

*****

 

I've decided to use one of my Linux machines. I'm using Lubuntu 20.04.

 

I've now unpacked Nop90's version of Karri's template. Apparently Karri's template has everything you need to program in C and in assembly, but Nop90 has added a few nice things to it. I got the zip file here:

This is what I did to install it, using instructions found here:

 

sudo apt-get install git checkinstall mednafen

git clone https://bitbucket.org/atarilynx/lynx.git
cd lynx/tools

make -f Makefile.deb

 

Then Unzip the template zip file in your desired location. I unzipped mine in the /lynx/ directory created in the previous step. Then after unzipping...

 

cd template

make

 

That seemed to work for me. So now I have a directory tree that looks something like this:

 

lynx/

   --> contrib/

      --> various things

   --> template/

      --> various things

   --> tools/

      --> bll/

      --> cc65/

      --> lynxer/

      --> lyxass/

      --> newcc65/

I love that I seem to have all the bits and pieces now. That was pretty easy, and I hope I pasted all that correctly into this post. As for what to do next, I don't know. I didn't see anything obvious. I think I have to read up on each of these tools to see what they do. And that can wait until next time.

 

 

 

Edited August 17, 2020 by OldAtAtari

[OldAtAtari]

Just linking a topic here. It gives good advice. Basically, that there is no perfect tutorial. Suck it up and teach yourself using resources around the web. And ask for help. There will always be helpers. And it's a fun read, too:

https://atariage.com/forums/topic/194086-teacher-for-lynx-programming-eheh/#comments

[OldAtAtari]

I decided to do some general reading about C programming and assembly programming, so I went on a hunt for free ebooks.

 

Amazon yielded a couple free C books which look good, but no assembly books. But then I found this book in a Google search:

 

Assembly Lines: The Complete Book by Roger Wagner

https://archive.org/details/AssemblyLinesCompleteWagner/mode/2up

It's specifically written to teach 6502 programming for the Apple II computer, but I figured it might serve well as a primer on assembly. It has the benefits of being professionally written, well-organized, slightly funny, and aimed at beginners, though it does assume that the reader has an understanding of the "BASIC" programming language.

 

Even though C might be easier, the draw of assembly is irresistible, so I've started reading this book. At some point, I think it will veer too much in the direction of the Apple and not be appropriate for Lynx programming, but for reminding myself of the ins and outs of pushing bytes around in assembly, so far, so good.

[Songbird]

Very cool, thanks for sharing all these steps and links! Lynx programming is fun, and I have done both -- actually wrote a couple of Lynx games in C ~20 years ago, but this year I am working on two pure assembly games.

 

[OldAtAtari]

3 minutes ago, Songbird said:

Very cool, thanks for sharing all these steps and links! Lynx programming is fun, and I have done both -- actually wrote a couple of Lynx games in C ~20 years ago, but this year I am working on two pure assembly games.

 

Songbird, thank you for the kind words! I know other people have attempted to do step-by-step tutorials in the past, but many of those seem outdated, incomplete, or are aimed at people with more existing knowledge than I have. So if I'm going to go to the trouble of learning these things, it seems good to document it for the future, though this too, may end up incomplete and outdated.

But anyway, it's good to have your support. I consider anyone who has completed a unique program that compiles and runs, to be an expert. And you've got multiple games done and more on the way, in assembly!!! That's exciting.

Please feel free to chime in at any point with thoughts, responses, or corrections. It's nice to have you onboard.

 

[sage]

On 8/5/2020 at 11:04 AM, OldAtAtari said:

      --> lynxer/

    

gosh, there is still someone using lynxer ... this only makes troubles

[OldAtAtari]

1 minute ago, sage said:

gosh, there is still someone using lynxer ... this only makes troubles

Was lynxer the assembler before lyxass came about?

[sage]

4 minutes ago, OldAtAtari said:

Was lynxer the assembler before lyxass came about?

no, it is the old ROM builder.

but it is a bit annoying as it can only create this "troyan horse" style card layouts.

you find a replacement on http://lynxdev.atari.org/ or newer on my github site

same for some bugfixed/patched version of lyxass.

if you use C wit the current cc65, it doesnt matter, as it embeds its own card layout and builder.

[OldAtAtari]

1 minute ago, sage said:

no, it is the old ROM builder.

but it is a bit annoying as it can only create this "troyan horse" style card layouts.

you find a replacement on http://lynxdev.atari.org/ or newer on my github site

same for some bugfixed/patched version of lyxass.

if you use C wit the current cc65, it doesnt matter, as it embeds its own card layout and builder.

Wow, so much to learn. So this doesn't matter if I use C. But if I use assembly, it does matter.

 

So I guess I need the replacement, then. And the newest is on your github? Can you provide a link to that?

 

And once I'm on your github, I should be able to get a lynxer replacement and a better version of lyxass. Is that right?

And everything I've gotten was from the 2019 template. And it's out of date already! Are there any other components I need to update?

Thank you for your help, Sage!

[sage]

the template is for cc65, not necessary for assember projects

[OldAtAtari]

2 minutes ago, sage said:

the template is for cc65, not necessary for assember projects

Mind blown! I thought it had all the pieces necessary for C and assembly.

Ok, so if you have a moment, would you mind sharing the list of tools I would need for assembly?

[sage]

https://github.com/bspruck/

 

you need:

lyxass

lyxass "libraries" -> includes/macros/vardefs

(and optional a rom builder, as most emulators and flash card tools can handle single-file-memory-living-programs directly)

optional: sprpck (for building sprites from pictures)

 

if you want to have a more complicated project, which contains several files dynamically loaded from card, title pic etc it gets complicated..

 

 

[OldAtAtari]

13 minutes ago, sage said:

https://github.com/bspruck/

 

you need:

lyxass

lyxass "libraries" -> includes/macros/vardefs

(and optional a rom builder, as most emulators and flash card tools can handle single-file-memory-living-programs directly)

optional: sprpck (for building sprites from pictures)

 

if you want to have a more complicated project, which contains several files dynamically loaded from card, title pic etc it gets complicated..

 

 

Thank you!

The includes/macros/vardefs... Are those all the files in your lyxass_patched directory? The .h files? Do I put them all in the same directory with lyxass?

And then lynxdir is the rom builder.

 

And then sprpck I can pick up from someplace else, assuming it's not already somewhere in my directory structure from the template.

 

And if I want a more complicated project... "it gets complicated." Funny! It's complicated already! As I'm reading about assembly, it seems easy enough to learn. The difficult part is the environment setup and all the tools. cc65, newcc65, bll, lyxass, lynxdir, sprpck, lynxer, and probably others. Some things are out of date, some things aren't needed, some things are needed for only C, and some things are for assembly. And I think I read that newcc65 is really the old cc65! cc65 is newer than newcc65. There is a world of programs here, some dating back to the late 90's. It's hard to understand what everything is. If I ever learn it, maybe I'll make a cheatsheet.

I'm sorry for that rant there. I admire all you folks for being able to keep these things straight. Maybe one day soon it will seem as simple to me as it is to you. I'm trying!

 

[sage]

you can use the "copy an already working environment" ansatz.

 

if you look into the chipper folder for example, you see that it compiles the music to a full rom as all tools and  sources are included. (for windows, and quite outdated)

[sage]

i am always to lazy to put some examples somewhere , but here you can see how i structure my makefiles

badapple.mak Makefile Makefile.base

[OldAtAtari]

16 minutes ago, sage said:

i am always to lazy to put some examples somewhere , but here you can see how i structure my makefiles

badapple.mak 1.18 kB · 2 downloads Makefile 232 B · 3 downloads Makefile.base 3.49 kB · 2 downloads

I'm a computer geek compared to most everyone I know, but when it comes to this stuff, I keep coming up against my ignorance and inability, so I really appreciate your assistance.

Right off the bat, I don't understand how to copy your "already working environment", and I don't see the clipper folder you're referring to. And I'm not sure where the make files fit into the process.

But I know you're giving me helpful stuff, and I really do appreciate it. I have to leave my computer for a bit (gonna go buy a couch!). I'll try to get back to this later tonight or this weekend to see if I can make some progress.

Sage, thanks again.

[42bs]

If you are new to C and Makefile, I recommend to do some programming on PC to get used to C. 

C on 8 bit machines is a totally different story.

 

Btw. newcc65 is a patched version of the cc65 back in the 90s . No github at that time, but I needed to name it differently to not confuse people back then.

 

As for lyxass , I think, mine is the most recent.

 

[sage]

It was somewhere hidden on my web site, which i did not update for loooong time.

I guess i should move  everything to github ... but i am too lazy to check the copyright things ?

 

https://github.com/bspruck/lyxass_lib

I normally softlllink al files into a single folder... thus some of my code might need pathname changes, like in

https://github.com/bspruck/badapple

 

[OldAtAtari]

1 hour ago, 42bs said:

If you are new to C and Makefile, I recommend to do some programming on PC to get used to C. 

C on 8 bit machines is a totally different story.

 

Btw. newcc65 is a patched version of the cc65 back in the 90s . No github at that time, but I needed to name it differently to not confuse people back then.

 

As for lyxass , I think, mine is the most recent.

 

Thanks, 42bs.

 

Right now I'm back focusing on assembly. If I'm gonna have to learn something anyway, why not go for the ultimate? And if it proves too daunting, I'll try C before I give up entirely. But it's good to know that I should practice on a PC. I've got some experience with Makefile, but not much. I've been trying to figure out how Makefile fits into this process, though. Maybe it's a C-only requirement and not needed for assembly.

So newcc65 is indeed newer than cc65? I had read otherwise elsewhere, so it's good that you have set me straight on that.

 

And you say your lyxass is the most recent, and sage says his is most recent. I vote for a cage match between the two of you! My plan for today is to write and compile something in assembly that will work on Handy. Hello World or maybe something simpler, even if it's just displaying the register contents. I bet the version of lyxass I got from the 2019 template will be just fine for that.

[OldAtAtari]

59 minutes ago, sage said:

It was somewhere hidden on my web site, which i did not update for loooong time.

I guess i should move  everything to github ... but i am too lazy to check the copyright things ?

 

https://github.com/bspruck/lyxass_lib

I normally softlllink al files into a single folder... thus some of my code might need pathname changes, like in

https://github.com/bspruck/badapple

 

Thank you, Sage! I'll experiment with these things later on. I'm hoping to get a simple program written today, and all this environment setup has gotten in the way. I'm getting bogged down in how to create the perfect setup instead of jumping in with an easy test case.

[Turbo Laser Lynx]

8 hours ago, OldAtAtari said:

So newcc65 is indeed newer than cc65? I had read otherwise elsewhere, so it's good that you have set me straight on that.

newcc65 is indeed the oldest one, I think you got it the other way around by accident, apparently the CC65 version that it builds upon is all the way from the 90s (that's so amazing/fun!) It still works fine for Lynx game development, and it's quite easy to setup on windows if I remember correctly. I used it for a bunch of minigames when I started out and it's really great. Some recent great efforts made with newcc65 are LordKraken's and agradeneu's Odynexus and LordKraken's Bombercats that come to mind. IIRC also Fadest develops his games in newcc64, a couple of his great games are Ynxa and the Yastuna games.

Personally I later switched to Karri's version because he started to make it really convenient to use for newbies/artists/tinkerers/"less programmatically inclined". I like cc65 remake / Karri's cc65 because of the available template(s) and make files. It's like a light game development framework really. Also it has cart loading support "out of the box", which is otherwise complicated to set up. That means you can develop bigger games more easily. There's been quite a lot of games made with this version. Karri has already made several games, and I already linked you my recent small games. Some notable games are Ninjabba's RPG "Wyvern Tales", Karri's "On duty", drLudos fun "Growing Ties" and nop90 has made many impressive Lynx games in a short time, for example Xump and Nutmeg.

Then as a third option there's also the official, up to date CC65. Some of the guys on this forum have been using this version of CC65 too, but I'm unsure of the level of support this version has here for the Lynx. I think you have to build up a lot from scratch yourself when using this. If I remember correctly at least atarigamer/Igor have made a couple of small games with it. There might be others too.

Some of the technically greatest games and demos that push the limits of the Lynx are inevitably assembly, a couple of great examples are enthusi's "Assembloids" game and "Bastion" demo. Zaku must have been written mostly in assembly as well, it runs perfectly in a fast framerate.

Zaku was and is indeed unbeliavable, but one should also take into consideration the development time and difficulty curve. Zaku took many years to develop, and it's indeed perfection, but once again it's all about what you're setting out to achieve and what's fun for you. In C you can potentially develop small games in a few weeks and bigger ones in a couple of months. If it's not a technical marvel you can even things out with nice gameplay, graphics and music.

*Sorry to all Lynx devs if I forgot to mention your fabulous homebrew game here in the examples, I wrote everything out of memory.

Edited August 8, 2020 by Turbo Laser Lynx

[OldAtAtari]

1 hour ago, Turbo Laser Lynx said:

newcc65 is indeed the oldest one, I think you got it the other way around by accident, apparently the CC65 version that it builds upon is all the way from the 90s (that's so amazing/fun!) It still works fine for Lynx game development, and it's quite easy to setup on windows if I remember correctly. I used it for a bunch of minigames when I started out and it's really great. Some recent great efforts made with newcc65 are LordKraken's and agradeneu's Odynexus and LordKraken's Bombercats that come to mind. IIRC also Fadest develops his games in newcc64, a couple of his great games are Ynxa and the Yastuna games.

Personally I later switched to Karri's version because he started to make it really convenient to use for newbies/artists/tinkerers/"less programmatically inclined". I like cc65 remake / Karri's cc65 because of the available template(s) and make files. It's like a light game development framework really. Also it has cart loading support "out of the box", which is otherwise complicated to set up. That means you can develop bigger games more easily. There's been quite a lot of games made with this version. Karri has already made several games, and I already linked you my recent small games. Some notable games are Ninjabba's RPG "Wyvern Tales", Karri's "On duty", drLudos fun "Growing Ties" and nop90 has made many impressive Lynx games in a short time, for example Xump and Nutmeg.

Then as a third option there's also the official, up to date CC65. Some of the guys on this forum have been using this version of CC65 too, but I'm unsure of the level of support this version has here for the Lynx. I think you have to build up a lot from scratch yourself when using this. If I remember correctly at least atarigamer/Igor have made a couple of small games with it. There might be others too.

Some of the technically greatest games and demos that push the limits of the Lynx are inevitably assembly, a couple of great examples are enthusi's "Assembloids" game and "Bastion" demo. Zaku must have been written mostly in assembly as well, it runs perfectly in a fast framerate.

Zaku was and is indeed unbeliavable, but one should also take into consideration the development time and difficulty curve. Zaku took many years to develop, and it's indeed perfection, but once again it's all about what you're setting out to achieve and what's fun for you. In C you can potentially develop small games in a few weeks and bigger ones in a couple of months. If it's not a technical marvel you can even things out with nice gameplay, graphics and music.

*Sorry to all Lynx devs if I forgot to mention your fabulous homebrew game here in the examples, I wrote everything out of memory.

 

Turbo Laser Lynx, as always, you encourage and inspire me. Thank you for that. I need it.

So you use the template similar to what I describe near the start of this topic? The one that looks more or less like this:

lynx/

   --> contrib/

      --> various things

   --> template/

      --> various things

   --> tools/

      --> bll/

      --> cc65/

      --> lynxer/

      --> lyxass/

      --> newcc65/

 

And of that, can you tell me which bits and pieces you use? cc65, not newcc65, right? And is lyxass your compiler? I know you've said that you write the C program in Windows and then compile it in Linux. For a barebones program, such as "Hello World", is it really that simple? And then for a full-blown game, you have the sprite and music generators to help. But at it's core, are we talking about notepadd++, cc65, and lyxass for your method?

Oh! And what do you do with these tools when they get updated? Apparently there are a couple updated versions of lyxass floating around that I could download and install over my template version. But is it wise and/or necessary to do so? My concern is that the template should get me a good working environment, and if I start overwriting parts of it with new versions, I might create some kind of conflict, breaking my environment.

[Turbo Laser Lynx]

It is actually potentially quite easy, of course it depends on all kinds of "IT" experience. The folder structure you show there is for collecting all kinds of Lynx development stuff in one place I think, so you would only need to:

Install Karri's cc65 onto your raspberry pi / linux machine, as per these instructions:
http://atariage.com/forums/topic/256753-atari-lynx-programming-tools-and-tutorials-wip/?p=4011786

- When cc65 is installed you can copy over the template somewhere to the linux machine.

 

Use Karri's newest template here:

http://atariage.com/forums/topic/287147-is-10-fps-a-too-low-framerate-for-a-lynx-tile-based-game/?p=4202302
 

Or use Karri's newest template with addons from Nop90 here:

http://atariage.com/forums/topic/290138-karris-cart-template-with-some-addons/?p=4256410

- When it's copied over you can navigate into the template folder, the folder structure should look something like this:

- If everything is installed properly you can just write 'make' and the whole game/cart template compiles. It puts the resulting game.lnx file (that you can run in an emulator) in the cart directory.

Then you can start experimenting changing stuff in the game.c code and in the intro.c code and recompile. In addition to looking at the c code it also makes sense having a little look at the makefiles. When you want to start adding stuff, for example more graphics, you have to list the files/objects in the make files.

- Stuff might start behaving weirdly if you don't do a 'make clean' from time to time.

This should get you started at least.

Edited August 9, 2020 by Turbo Laser Lynx