Atari Lynx programming tutorial

[sage]

Not present in the Lynx 1, but included in the Lynx 2.

[LX.NET]

Not present in the Lynx 1, but included in the Lynx 2.

 

Cool, I will have to check that out. I had no idea the Lynx 2's Mikey is a more modern 6502 than the Lynx 1's.

[LX.NET]

I have added Part 18: Files to the tutorial series. It was a tough one to write and took me a couple of rewrites to be satisfied with the flow.

As always, please proof-read this for any technical errors, things that are unclear or deserve more explanation, even spelling and typing errors.

Hope you enjoy this part.

Suggestions for the next part are welcome.

[BadPricey]

Hi,

I've just started working through the tutorial and I'm just getting the environment setup. With the CC65 part I had to copy and paste it to the C:\Program Files it would not extract there. I have installed Visual C++ it seems to have installed ok. I downloaded the Hello World.zip to check it loaded into Visual C++ ok and it did. When I do the build I get this result, slightly different to yours, have I done something wrong?

 

1>------ Build started: Project: Starter, Configuration: Debug Win32 ------
1>
1> Microsoft ® Program Maintenance Utility Version 10.00.30319.01
1> Copyright © Microsoft Corporation. All rights reserved.
1>
1> cc65 --code-name CODE --rodata-name RODATA --bss-name BSS --data-name DATA -I . -t lynx --add-source -O -Or -Cl -Os game.c
1> ca65 -o game.o game.s
1> cl65 -t lynx -o game.lnx lynx-160-102-16.o lynx-stdjoy.o game.o lynx.lib
========== Build: 1 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

 

Any advice greatly appreciated.

Rgds

Mark

[LX.NET]

Any advice greatly appreciated.

It seems to have compiled OK. Is there any problem with the output?

Could it be that you had more than one try. It seems that the tgi and joy libraries have already been created by co65.

Did you get a working game.lnx?

 

BTW: great you got started. The hardest part might just be seting up the environment. Please stick with it as it will pay off.

Edited October 12, 2014 by LX.NET

[+karri]

It seems to have compiled OK. Is there any problem with the output?

Could it be that you had more than one try. It seems that the tgi and joy libraries have already been created by co65.

Did you get a working game.lnx?

 

BTW: great you got started. The hardest part might just be seting up the environment. Please stick with it as it will pay off.

 

Nice to have a new programmer on board.

 

LX.NET, I checked the tutorial of TGI functions and there is one thing that might be worth mentioning.

 

The color index 0 is used as transparency. Unfortunately it is also COLOR_BLACK. So typing text in COLOR_BLACK produces nothing.

 

The work-around is to type in COLOR_DARK_BROWN instead. The result is very similar.

 

This may be very confusing for a starting programmer who decides to type black text on a white canvas.

 

--

Karri

[BadPricey]

It seems to have compiled OK. Is there any problem with the output?

Could it be that you had more than one try. It seems that the tgi and joy libraries have already been created by co65.

Did you get a working game.lnx?

 

BTW: great you got started. The hardest part might just be seting up the environment. Please stick with it as it will pay off.

 

 

 

Nice to have a new programmer on board.

Karri

 

Hi there,

Many thanks for responding. I do have a game.lnx file that has been created. When I load up the Handy debugger I point it to the game.lnx file but it does not load, I get an error stating lynx has stopped working, check for a solution online or close the program. However when I load the game.lnx file in regular Handy it seemed to work ok. I guess therefore I have the developement environment setup? Here is a small screenshot of it working, I modified the output slightly.

I wouldn't class me as a programmer Karri, I'm just inquisitive and would like to complete LX.NET's brilliant Lynx tutorial. Fingers crossed though something may materialise in the future.

[GadgetUK]

Great stuff! Nice to see someone else looking to develop for the Lynx =D I've not tried the debug version of Handy, maybe it's expecting some switches or something?

[+karri]

I wouldn't class me as a programmer Karri, I'm just inquisitive and would like to complete LX.NET's brilliant Lynx tutorial.

Modifying existing sources to do something different and getting it to work on a real Lynx. Hmm.

 

I stand with my previous statement

[+karri]

Great stuff! Nice to see someone else looking to develop for the Lynx =D I've not tried the debug version of Handy, maybe it's expecting some switches or something?

The original Handybug wanted 128k or 256k carts. It did not understan shorter binaries.

 

-

Karri

[LX.NET]

Hi there,

Many thanks for responding. I do have a game.lnx file that has been created. When I load up the Handy debugger I point it to the game.lnx file but it does not load, I get an error stating lynx has stopped working, check for a solution online or close the program. However when I load the game.lnx file in regular Handy it seemed to work ok. I guess therefore I have the developement environment setup? Here is a small screenshot of it working, I modified the output slightly.

I wouldn't class me as a programmer Karri, I'm just inquisitive and would like to complete LX.NET's brilliant Lynx tutorial. Fingers crossed though something may materialise in the future.

lynx.png

Seems OK to me.

It appears the Debug version of Handy simply crashes in Windows. It might be corrupt or perhaps it doesn't have enough rights to execute properly (did you Unblock the zip archive before extracting?)

I might do the next part of the tutorial on debugging. You will need the debug version of Handy for that, but normally the regular Handy is adequate.

Thanks for the complements on the tutorial. It was written for people like yourself. Please mention any errors or gaps in the series. I know it doesn't say enough on joystick for example.

Feel free to keep asking any questions.

[BadPricey]

 

Please mention any errors or gaps in the series. I know it doesn't say enough on joystick for example.

Feel free to keep asking any questions.

 

Hi there,

I really struggled with Part 4 :Creating a project, The first bit worked ok starting a Makefile project, skipped the wizard bit and put in the configuration properties ok. However I could not add new text files “game.mak” and “lynxcc65.mak” to the project.

I therefore copied the original Starter project of "Hello World" and called it example. This had the required files. I copied and pasted the rest of the text from your site into the relevent sections, deleted all the content that was already in them. When I click build it fails quite badly and I don't understand much of it. There are some differences to the text in your example on Part 4 and the "Hello World" example. You will have to excuse me for not understanding the errors, if I become a burden on your time please tell me. Here's the errors. Only thing I can notice is the backslashes become forward slashes. Again any help greatly appreciated.

 

1>C:\Program Files\CC65/include/6502.h(128): warning : Implicit `int' is an obsolete feature

1>C:\Program Files\CC65/include/6502.h(128): error : `)' expected

1>C:\Program Files\CC65/include/6502.h(128): error : `{' expected

1>C:\Program Files\CC65/include/6502.h(128): error : Undefined symbol: `stack_size'

1>C:\Program Files\CC65/include/6502.h(128): warning : Statement has no effect

1>C:\Program Files\CC65/include/6502.h(128): error : `;' expected

1>C:\Program Files\CC65/include/6502.h(128): error : Expression expected

1>C:\Program Files\CC65/include/6502.h(128): warning : Statement has no effect

1>C:\Program Files\CC65/include/6502.h(131): error : Expression expected

1>C:\Program Files\CC65/include/6502.h(131): warning : Statement has no effect

1>C:\Program Files\CC65/include/6502.h(131): error : `;' expected

1>C:\Program Files\CC65/include/6502.h(131): error : Call to undefined function `reset_irq'

1>C:\Program Files\CC65/include/6502.h(131): error : Expression expected

1>C:\Program Files\CC65/include/lynx.h(81): error : Expression expected

1>C:\Program Files\CC65/include/lynx.h(81): warning : Statement has no effect

1>C:\Program Files\CC65/include/lynx.h(81): error : `;' expected

1> C:\Program Files\CC65/include/lynx.h(81): Fatal: Too many errors

1>NMAKE : fatal error U1077: '"C:\Program Files\CC65\bin\cc65.EXE"' : return code '0xff'

1> Stop.

1>C:\Program Files (x86)\MSBuild\Microsoft.Cpp\v4.0\Microsoft.MakeFile.Targets(38,5): error MSB3073: The command ""C:\Program Files (x86)\Microsoft Visual Studio 10.0\VC\bin\nmake.exe" /f game.mak BUILD=Debug all" exited with code 2.

========== Build: 0 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

 

Rgds

BadPricey

 

[+karri]

Hi BadPricey,

 

the problem here is that for some reason the compiler cannot find your include files properly. That is the reason for the first error in the list. Obviously it has a problem knowing what "size_t stack_size" means.

 

You could be nice and tell the compiler that the include files are found in C:\Program Files\CC65/include. In Windows all the environment variables should be ok by default. Perhaps you have messed them up in your nmake somehow.

 

My guess is that the path "C:\Program Files" has a space in it. So the include system looks for the files at "C:\Program\include" or something like that. You may need to use "" marks around your command line variables to make them work.

 

From the FAQ on the cc65.org site:

 

A: The compiler and the linker must know how to find the include files and libraries. A standard path is compiled into the binaries, but this path works only for Unix machines (provided that the include files and libraries are installed in this path, which is true if you're using one of the precompiled packages).

When running the tools under Windows or DOS, you have to tell them where the support files are installed. This is done by setting one or more of the environment variables:

• CA65_INC (points to directory with assembler include files)
• CC65_INC (points to directory with compiler include files)
• LD65_CFG (points to directory with linker config files)
• LD65_LIB (points to directory with libraries)
• LD65_OBJ (points to directory with object files)
• CC65_HOME (points to the cc65 file tree. If you have this one, you usually won't need the others).

As an DOS/Windows example, if you have installed cc65 in c:\cc65, you should use

    set CC65_HOME=c:\cc65    	

Note: The Windows .exe installer package will set all necessary variables for you, so Windows users are encouraged to use it instead of the .ZIP file distribution.

Unix people usually don't have a problem setting environment variables, so I don't explain the Unix syntax here:-)

[BadPricey]

Hi karri,

Thanks for replying. I have managed to get the developement environment setup successfully prior to this part of the tutorial. I guess therefore that the environment variables are set correctly. Its when I try and follow the tutorial Part 4 creating a project it just doesn't work for me. I have subsequently tackled Part 5 using the Hello World setup files game.mak, lynxcc65.mak and game.c with good results.

I will try again just in case I made an obvious error.

Rgds

BadPricey

[LX.NET]

Hi there,

I really struggled with Part 4 :Creating a project, The first bit worked ok starting a Makefile project, skipped the wizard bit and put in the configuration properties ok. However I could not add new text files “game.mak” and “lynxcc65.mak” to the project.

I therefore copied the original Starter project of "Hello World" and called it example. This had the required files. I copied and pasted the rest of the text from your site into the relevent sections, deleted all the content that was already in them. When I click build it fails quite badly and I don't understand much of it. There are some differences to the text in your example on Part 4 and the "Hello World" example. You will have to excuse me for not understanding the errors, if I become a burden on your time please tell me. Here's the errors. Only thing I can notice is the backslashes become forward slashes. Again any help greatly appreciated.

Just wondering about a couple of things.

Can you check the version of your CC65? Go to the CC65 folder and do a

CC65 --version

That's with a double - sign.

 

Mine reads:

 

CC65 V2.13.9

SVN version: 5944

 

What does yours say?

 

Also, how did you try to add files to the project? It should always do that properly I would say, as to Visual Studio the actions of the Make file are not related to the project and its files.

 

I rewrote parts of part 4, and updated it so it is less picky about the Visual Studio version. It seems to work alright (on my machine )

Hope it helps.

[BadPricey]

Hi LX.NET,

I did check this the other day but must have forgot to post the info to you sorry.

I am running cc65 V2.12.3 SVN version: 5495. I used the link in your tutorial.

I did pm you to say that I think I solved my issue.

 

However I have a few more questions from the sprite's section but I'm not even sure if I am asking the right question. I am so confused with the hexadecimal system used. Is it better if I try and understand hexadecimal then try and follow the tutorial?

 

Could you do me a huge favour and possibly add it to the tutorial. It will be an easier reference for a beginner (I think) With regards to the sprite data can you list all the parameters that a sprite can use with values and adjacent to it add comments refering to each value. I know you have commented underneath but having it alongside might be an easier reference.

 

Heres my example of what I mean: please correct any of my errors I'm just adding what I think I know.

 

typedef struct SCB_RENONE { // unsure what scb_renone means? would the next sprite scb be scb_rentwo?
unsigned char sprctl0; //scb control byte (please elaborate)
unsigned char sprctl1; //scb control byte (please elaborate)
unsigned char sprcoll; //scb control byte (please elaborate)
char *next; //pointer to next scb
unsigned char *data; //(please elaborate)
signed int hpos; //x position
signed int vpos; //y position
} SCB_RENONE;

 

And then how the data from above fits the SCB of the sprite in a similar fashion

 

extern unsigned char robot[]; //robot array
SCB_RENONE robotsprite = {
BPP_4 | TYPE_NORMAL, //color depth | what is this?
REUSEPAL, 0x01, //specify palette, collision x,y
0x0000, // not chaining new sprite
&robot, //pixel data
20, 50 // draws at x,y
};

 

I have used a program to create some games years ago called Gamemaker. I know its completely different to Lynx programming, which at the minute I am finding complicated to say the least. I don't want to give up and I will try and persevere. Is there a point where I should just say 'Hey this isn't for me?'

 

Where can I find sprpck.exe to create sprites? I've searched my computer but cannot find it, or do I use a regular paint program?

 

Thanks in advance

BadPricey

Edited October 20, 2014 by BadPricey

[LX.NET]

Hi BadPricey,

 

It would be better for you to understand hexadecimal first. Their is a lot of hex values going around, and it helps to understand it all a bit better. Here are a few comments to give you a head start (I might put this in a tutorial part later):

 

Hexadecimal is a base-16 number notation. Think of it as the number system for people with two times 8 fingers on each hand. They will count from one to 16 but only need a single digit to express that number. So, after 9 you cannot use 10, because that would be 16 (10 is the all fingers used number). You will need more numbers, and that's why after 9 there is A (for decimal 10), B (decimal 11) to F (decimal 15). To distinguish hex from decimal you prefix a hex number with 0x in the C language (in assembly language this would be $).

 

Hexadecimal is useful, because it is a compact notation for 8-bit numbers using two digits in hex. And the 8-bit numbers are essentially 8 switches that can be on and off.

Hope this helps to get the right mindset when reading other tutorials on this. Again, I might do a part 0 for this, but it will not be soon.

 

typedef struct SCB_RENONE { // unsure what scb_renone means? would the next sprite scb be scb_rentwo?
unsigned char sprctl0; //scb control byte (please elaborate)
unsigned char sprctl1; //scb control byte (please elaborate)
unsigned char sprcoll; //scb control byte (please elaborate)
char *next; //pointer to next scb
unsigned char *data; //(please elaborate)
signed int hpos; //x position
signed int vpos; //y position
} SCB_RENONE;

 

And then how the data from above fits the SCB of the sprite in a similar fashion

 

extern unsigned char robot[]; //robot array
SCB_RENONE robotsprite = {
BPP_4 | TYPE_NORMAL, //color depth | what is this?
REUSEPAL, 0x01, //specify palette, collision x,y
0x0000, // not chaining new sprite
&robot, //pixel data
20, 50 // draws at x,y
};

 

You almost have it. SCB_RENONE is SCB_RE_NONE, so not ren_one. The RE might stand for REload, as it indicates which optional reloadable registers follow. If you do not reload, they will hold their previously set value (from the last sprite SCB that did reload these).

The sprite control block 0 and 1 define how the sprites behave. They are explained in later tutorial parts (7, 8 and 9). REUSEPAL means that the palette that is currently set in the hardware is reused. It implies that there is no palette data in the SCB. The collision number is just a number for the sprite. 0x01 simply means 'one' in hexadecimal. The normal type TYPE_NORMAL is also for the type of sprite. There are other sprite types, like shadow. That is explained in part 10.

 

Where can I find sprpck.exe to create sprites? I've searched my computer but cannot find it, or do I use a regular paint program?

sprpck.exe is the sprite packer. It is not a drawing program like Paint, but a tool that creates sprite data. I found that the Visual Studio (Visual C++ Express) bitmap editor can do the job, but it is clumsy. Gimp has been my goto tool, because it works well with the palette you should define to get correct colors. It is a larger and more complex tool. I would prefer something as simple as mspaint, but there doesn't seem to be one. Hence Gimp.

[LX.NET]

Two things I forgot to mention: you might want to download the latest known stable build from the first post of the tutorial series.

http://atariage.com/forums/topic/206456-atari-lynx-programming-tutorial/

And sprpck.exe is found in the BLL toolkit here: http://monlynx.de/lynx/tools.html at the sprite packer link.

[+karri]

LX.NET, what about a sp65 tutorial?

 

sprpck is great but in the cc65 toolchain we have sp65.

 

sp65 -r intro.pcx -c lynx-sprite,mode=literal,ax=10,ay=10 -w intro.c,ident=intro

 

It also supports packed and shaped. The "shaped" is a mode where the line from anchor to right and anchor to left is cut when you reach your edge index.

 

sp65 -r intro.pcx -c lynx-sprite,mode=shaped,ax=10,ay=10,edge=0 -w intro.c,ident=intro

 

With the edge you can create non-square sprites that do not rely on transparency. This means that the sprite can have 16 colors instead of just 15.

 

The shaped mode has a new parameter "edge". In the image below I draw the transparent background in COLOR_PINK which is index 2. So the last shape has -c lynx-sprite,ax=22,edge=2 to cut away the pink but leave the black outline with index 0.

 

The first tree is literal, second is packed third is shaped

 

[MantaNZ]

This is awesomeness. I'm currently making a racer for Mega Drive and was wondering how I'd go about porting it for the Lynx

[LX.NET]

if you need any help please let me know. Or if you are missing certain information in the tutorial (which are there)...

This is awesomeness. I'm currently making a racer for Mega Drive and was wondering how I'd go about porting it for the Lynx

[MantaNZ]

Awesome, thanks

[pixelperfect]

This is so great, thanks a bunch! Can't wait to get started hacking something together

[pixelperfect]

Up and running!

 

I was getting build errors from having a space in the Program Files directory, but I wasn't sure how to fix it so I just moved the CC65 folder to C:\ for now..

Edited August 17, 2016 by pixelperfect

[GadgetUK]

Great job!!! Get coding!!!