LowRes Coder Framework

• Example
• Interpreter
• Library
• Pixel-Buffer
• Raster
• Scrolling
• Music
• Sounds

SP4CEBAR 2024-07-15 10:18 (Edited)

A framework to simulate the graphics, sound, and IO of the original LowRes Coder.

Currently, it supports the gamepad and sprites, sound, and it has its raster effects installed.

Porting guide:

1. Remove the demo code from the "your code" section.
2. Add a label and a RETURN to the "your code" section and add a GOSUB call from the first few lines of this framework to this section.
3. copy your LowRes code to the "your code" section of the program.
4. replace each LowRes Coder command like "DEF SPRITE" with a subprogram call prefixed with "LOWRES_" like "CALL LOWRES_DEF_SPRITE()"
   • which
     • up, down, left, right, sprite hit, and hit are identical in both LowRes versions and do not need a replacement subprogram (but I added them just in case someone forgets this)
     • BUTTON and BUTTON TAP may seem identical, but a LowRes Coder button includes touch and tap when on gamepad 0.
     • SPRITE and SPRITE OFF are identical, yet this needs to be a separate subprogram because the graphics are complicated.
     • Some functions can be replaced with an array; currently, none are.
     • string and math operations have not changed with the introduction of NX, so those don't need a replacement subprogram either.
   • how
     • to omit a parameter, simply pass the parameter "OMIT_T".
     • if there are words used as parameters, you should add them to the subprogram name.
     • Any subprogram that returns a value has that value as its first parameter, the value will be returned through this parameter.
     • subprogram names cannot contain the "$" character, so any string function replacement subprogram will not have it in its name.
   • errors
     • Symbol Name Too Long
       • remove characters from the end of the subprogram name until the error disappears (usually it is a single character, examples LOWRES_DEFINE_SOUND_LINE, LOWRES_SPRITE_PALETTE)
     • Syntax Error
       • Check if you added the subprogram's brackets
       • in LowRes Coder parameters can sometimes be omitted by leaving behind commas, to turn this into a subprogram, simply pass the "OMIT_T" variable.
     • Variable Not Initialized
       • In LowRes Coder it is fine to leave a variable uninitialized, in NX it's not. You can resolve this by simply initializing the variable with the value zero at the start of your code.
     • Type Mismatch
       • In LowRes Coder it is completely normal to add a value to a string, in NX that is not done. You can resolve this by wrapping the value in the STR$() function.
       • it is also possible that a value is passed to a string field, in which case you should also wrap the value in the STR$() function.
       • you can't pass OMIT_P to a string, because OMIT_P is not a string.
     • Argument Count Mismatch
       • In LowRes Coder you can omit the last parameters of certain functions. To turn this into a subprogram simply pass the "OMIT_T" variable to the end until this error disappears.
     • Too Many Tokens
       • unfortunately, this library takes quite a lot of code, you could try reducing the size of your imported program
5. General differences
   1. The LowRes Coder syntax is less strict than NX's, here are some examples:
      • In LowRes Coder you can use a variable that has not been initialized, in NX this variable should be initialized with the value zero before it is used.
      • In LowRes Coder it is also okay to add a value to a string, in NX this value should be wrapped in the STR$() function.
   2. you can't pass a function to the ON PAUSE GOTO function, so instead there is a GAME_PAUSED label which is run whenever pause handling is disabled and the game is paused, here you can put your pause handler logic.
   3. I don't know a way to detect the program exit, so the ON END GOTO function can't be made

Based on

• Character Data Tools

Credits

• LowRes Coder Demos by Timo Kloss
  • LowRes Galaxy
  • Parallax Scroller

Timo 2024-07-15 10:31

Good luck :O

SP4CEBAR 2024-07-15 11:47

Thanks, I'll need it

SP4CEBAR 2024-07-16 15:45 (Edited)

Update 1

• The LowRes coder's display command will stretch out the scene vertically using raster effects, this will help to save characters.
  • there are different raster effects, some can stretch out size-3-sprites (32x32 pixels) so that they can be used as additional background layers.
  • others can also copy character data, which will only be needed once the framework detects a shortage of available character RAM
• The LowRes Coder's sound commands are supported! With an audio queue and sound parameters, it just sounds slightly different.

It's tricky to tweak the sound conversion functions because an LFO isn't the same as a sound line, and not all conversion factors are given inside the documentations.

For example, I assume the non-linear LFO rate of NX is an exponential function with a base of ( 18Hz / 0.12Hz ) ^ ( 1 / 15 ) = 1.396602, also I'm not sure what the offset values are of the LFO's pitch and pulse width modulations.

These functions will convert LowRes Coder's sound parameters to NX's:

SUB LOWRES_DEF_SOUND( INSTRUMENT, WAVE_, PULSE, TIME )
  BUFFER_VOICE = 3
  SOUND BUFFER_VOICE, WAVE_, PULSE * 15, TIME * 60
  CALL COPY_INSTRUMENT( BUFFER_VOICE, INSTRUMENT, 0, 4 )
END SUB

SUB LOWRES_DEF_SOUND_LIN( INSTRUMENT, TIME, PITCH, PULSE )
  IF TIME <= 0 THEN EXIT SUB
  BASE_FREQUENCY   = 0.12
  TOP_FREQUENCY    = 18
  FREQUENCY        = 1 / TIME
  EXPONENTIAL_BASE = ( TOP_FREQUENCY / BASE_FREQUENCY ) ^ ( 1 / 15 )
  'EXPONENTIAL_BASE = 1.396602
  LFO_RATE         = LOG( FREQUENCY / BASE_FREQUENCY ) / LOG( EXPONENTIAL_BASE )
  PITCH            = PITCH
  PULSE            = PULSE * 2
  'PULSE = 0
  IS_NEGATED = PULSE <= 0 AND PITCH <= 0
  CALL CLAMP( LFO_RATE, 0, 15 )
  CALL CLAMP( PITCH   , 0, 15 )
  CALL CLAMP( PULSE   , 0, 15 )
  BUFFER_VOICE = 3
  LFO BUFFER_VOICE, LFO_RATE, PITCH,, PULSE
  LFO WAVE 3, 1, ABS( IS_NEGATED ), 1, 1
  CALL COPY_INSTRUMENT( BUFFER_VOICE, INSTRUMENT, 4, 3 )
END SUB

SUB CLAMP( V, L, H )
  V = MAX( L, MIN( H, V ) )
END SUB

SP4CEBAR 2024-07-16 16:09 (Edited)

Update 2

• fixed a crash that would occur on the NX browser player: it didn't like to find a "PAUSE" parameter when automatic pause handling was still enabled.

SP4CEBAR 2024-07-18 10:08

I think LowRes Coder's parallax scroller is a good benchmark and demo for this project.

SP4CEBAR 2024-07-18 11:25 (Edited)

Update 3

• sharpened the audio player's timing thanks to patch note 1.6 from my Midi Tools. In this case, it shouldn't save multiple timer variables, instead it should add each next duration to a duration variable. Pausing and resuming is different now. When paused, it removes the current timer to remove this time dependency and leave behind the next note delays, when resumed it adds the current timer to add an up-to-date time dependency to the next note delays.
• sprites kind of have a set of images now.
• gamepads can now switch between 0 and 1 players.
• I ported the Parallax Scroller demo from LowRes coder. Uncomment the second line of the program to listen to its gorgeous tunes.

SP4CEBAR 2024-07-23 11:03 (Edited)

Update 4

• Ported the LowRes Galaxy demo from LowRes Coder (it now has two demos loaded)
• some progress has been made on sprite zooming.

SP4CEBAR 2024-07-23 13:55 (Edited)

Update 5

• imported most of character data tools. Now there are barely any tokens left...

was8bit 2024-07-23 14:31

Try testing with this ;)

Mule...nx | Open in app

2024-07-23 14:31

SP4CEBAR 2024-07-23 15:12 (Edited)

Cool game! I think the LowRes Galaxy and the Parallax scroller will be plenty to test the main features of this library. Once this library works, I may look into sophisticated programs like yours.

The main challenges with developing this library are:

1. The limited amount of character ROM
2. The large screen size of sprites (especially in lower resolutions)
3. The processing speed of NX (it has to perform a lot of tasks)
4. The tokens (apparently it requires a lot of code)

was8bit 2024-07-23 15:22

:)

SP4CEBAR 2024-07-23 15:35 (Edited)

Interestingly, LowRes Coder's 0.04 second smallest wait time is only 25 frames per second, and LowRes Galaxy even uses a 0.05 second wait time (20 fps) so performance shouldn't be that much of a problem anymore as it has two or three frames available for one game loop.
The disadvantage is that the user's tap controls don't work that well yet with all those delays

SP4CEBAR 2024-07-23 16:17 (Edited)

I just noticed that LowRes coder's tap only starts to miss some taps when the delay is at least 0.08 seconds, which is twice the minimum, this is easier to implement

SP4CEBAR 2024-07-23 20:56 (Edited)

Update 6

• tap works more reliably now.. at least for programs with a loop waiting time of 0.05 seconds.
• most graphics functions have been assigned to their character data tools equivalent
• the token count is at its limit
• the LowRes Galaxy demo has been ported further as it used to only have the title screen.
• raster effects and sprite character loading have been disabled for now in favor of the pixel graphics

SP4CEBAR 2024-07-23 21:02 (Edited)

Update 7

• the parallax scroller demo looks better than the LowRes Galaxy demo

SP4CEBAR 2024-07-23 21:07

If you leave the song playing for long enough, eventually the sound queues become full, and it struggles with playing.

SP4CEBAR 2024-07-23 21:12 (Edited)

Project phases:

1. Fixed-pixel-size backgrounds (no zooming efforts)
2. Character RAM optimizations and multiple backgrounds (lower resolutions allow for even more backgrounds, also large sprites can be used as background layers )
3. Sprites and further character RAM optimizations
4. Zooming efforts with raster scrolling
5. optimizations for huge sprites at low resolutions

SP4CEBAR 2024-07-26 21:22 (Edited)

Update 8

• the text command works now
  • the demo uses LowRes Coder's SCROLL which is like NX's BG SCROLL, the current implementation will copy and paste pixels without clearing the underlying pixels, which results in the text becoming a mess of overly overlayed characters
• TEXT WIDTH works
• ON PAUSE GOTO now accepts a string and stores it into the G_PAUSE_HANDLER$ variable
• LowRes Coder's PRINT works... until it reaches the bottom of the screen and throws an error.
• The LowRes Galaxy demo has been excluded to save on tokens, with the new additions the program now uses almost 14000 tokens of the 16384

SP4CEBAR 2024-07-26 22:52 (Edited)

Update 9

• added three more background layers

SP4CEBAR 2024-07-26 22:58 (Edited)

Update 10

• added the LAYER DISPLAY command (I didn't know its function until now)

SP4CEBAR 2024-07-26 23:03

Update 11

• Centered the screen

SP4CEBAR 2024-07-27 00:38 (Edited)

Update 12

• made SCROLL CLEAR work using a buffer (on the same layer (temporary fix))
  • it always moves two to the left no matter what parameters are used, so that's why the text scrolls twice as fast and has double the spacing between them CCOP6 is hard to control
• clamped text outside the visible area into the visible area as a temporary fix so you can see the demo text!

SP4CEBAR 2024-07-27 00:54

14857 tokens :)

SP4CEBAR 2024-07-27 01:29

Update 13

• added a palette to each background layer and a system to load a requested color into the palette

SP4CEBAR 2024-07-27 09:09

Update 14:

• sprites are enabled again, and their required characters are borrowed from layer 3, sprites don't have the proper zoom, sprite layer, or position offset to the center of the screen
• bg view 1 was set off on display 4, so it has to be turned on on any other display
• I tried to remove the blue bar, but it turns out to be an artifact of the current SCROLL CLEAR implementation

SP4CEBAR 2024-07-27 14:42 (Edited)

It is important that none of the subprograms modify any of the parameters passed to them as this will return a value which may modify a variable and alter the working of the LowRes program, or worse, it may modify a passed constant like OMIT_T

The subprograms shouldn't but might

SP4CEBAR 2024-07-27 19:00

Update 15

• a smarter color manager utilizes the three available colors per layer more efficiently
• sprites would now be offset to the center of the screen just like the background layers

SP4CEBAR 2024-07-27 19:59 (Edited)

Update 16

• new commands for layer visibility and color modifying:
  • palette
  • =palette (called LOWRES_PALETTE_GET( RETURN_VALUE, INDEX ), or you could use the G_LAYER_COLORS( G_LAYER, INDEX ) array
  • palette clear
  • LAYER ON
  • LAYER OFF
  • LAYER CLOSE now works like LAYER OFF
  • LAYER OPEN now views the layer like LAYER ON
• LAYER SCROLL and LAYER DISPLAY now save their scroll values

SP4CEBAR 2024-07-27 20:10

Update 17

• slight optimization: removed the condition from the four "ELSE IF LAYER_NUMBER >= 2 THEN" lines because ELSE will suffice

SP4CEBAR 2024-07-27 21:22

To do

1. fix LowRes SCROLL
2. work on flood fill add the PAINT command

SP4CEBAR 2024-07-28 16:10 (Edited)

The SCROLL CLEAR buffer (the lower text in the demo) is one ahead of the original (the upper text), so I think that my copying code always moves it one pixel to the left. Two copies cause a motion of two pixels to the left

Timo 2024-07-28 21:45

Seems like this little project went slightly out of control and became giant :O
Anyway, its results look interesting :)

SP4CEBAR 2024-07-29 10:31

I think so too... Thank you!

TrashCan Games 2024-07-31 09:08

This is really cool, Ill definitely get some cool uses out of this. I might try port some lowres coder programs over like stoners delight

SP4CEBAR 2024-08-01 19:16 (Edited)

Thank you!
Don't expect it to work as well though, certain features may be incomplete or missing, I can't guarantee that sprites work at all, user input should work, and most background graphics should work, but there may be some hidden bugs.
Anyways, good luck porting :)

SP4CEBAR 2024-11-18 17:26 (Edited)

I just browsed through the code and thought I could save some tokens by removing unrelated graphics API functions and making general shape-drawing functions: a parametric plotter and an area-between-two-math-functions plotter.

The new tokens could be used for an implementation of the PAINT command