compudanzas/src/intro_to_uxn_programming.gmo

# intro to uxn programming workshop

online workshop to learn the basics of {uxn} programming

# upcoming

=> https://withfriends.co/event/13004513/babycastles_academy_intro_to_uxn_programming Babycastles Academy: Intro to Uxn Programming
sunday, november 21, 12021, at 3pm UTC-5 (EST)

# description

Have you wondered how computers function under layers of abstraction? Are you curious about learning about assembly languages? Would you like to try fun challenges, while getting to know a permacomputing platform? Join us in learning about Uxn!

Uxn is a portable 8-bit virtual computer inspired by forth-machines, capable of running simple tools and games, and programmable in its own unique assembly language called Uxntal.

Uxn is at the core of Varvara computer, a platform for running small audio/visual applications. Varvara has been ported already to several years old and modern computing platforms, like the Gameboy Advance, Nintendo DS, the Playdate, and more.

In this workshop we'll introduce the basic concepts to start programming this computer: its architecture, the programming paradigms of Uxntal, and some low-level aspects that will allow us to create a simple drawing tool!

Pre-requisites: This workshop is best for those with some previous programming experience. However, no previous experience with assembly or low-level computing is needed.

We will use the learn-uxn website by metasyn, that requires a web browser with javascript enabled: 
=> https://metasyn.github.io/learn-uxn learn-uxn

# outline

## 1) uxn, varvara, and its architecture

* what is uxn, varvara, uxntal?
* varvara computer architecture

## 2) uxntal basics

* the stack and postfix notation
* hexadecimal

## 3) drawing into the screen

* setting system colors
* uxntal labels
* drawing a pixel

## 4) sprite drawing

* designing a sprite
* drawing a sprite

## 5) interactivity loop

* draw loop: on-screen vector
* reading the mouse

## 6) conditional behavior

* a small conditional example
* more possibilities

# links and resources

## for the workshop

=> https://metasyn.github.io/learn-uxn/ learn-uxn by metasyn
=> https://wiki.xxiivv.com/site/uxn.html uxn technical documentation
=> https://wiki.xxiivv.com/site/uxn.html varvara documentation documentation
=> https://akkartik.github.io/mu/tutorial/converter.html decimal to hexadecimal converter
=> https://100r.co/site/nasu.html 100R - nasu spritesheet editor
=> ./hexadecimal.gmi {hexadecimal}

## and more 

=> ./uxn_tutorial.gmi {uxn tutorial}
=> https://wiki.xxiivv.com/site/uxntal_reference.html the uxntal opcode manual
=> https://wiki.xxiivv.com/site/uxntal_cheatsheet.html uxntal cheatsheet
=> https://git.sr.ht/~rabbits/uxn uxn repository
=> https://llllllll.co/t/uxn-virtual-computer/ llllllll forum
=> https://github.com/hundredrabbits/awesome-uxn awesome uxn: awesome things from the community
=> https://100r.co/site/uxn.html 100R - uxn

irc channel: #uxn on irc.esper.net

# example program

```
( simple drawing tool )

( devices )
|00 @System  [ &vector $2 &pad $6  &r $2 &g $2 &b $2 ]
|20 @Screen  [ &vector $2 &width $2 &height $2 &pad  $2 &x $2 &y $2 &addr $2 &pixel $1 &sprite $1 ]
|90 @Mouse [ &vector $2 &x $2 &y $2 &state $1 &wheel $1 ]

( init )
|0100 
@on-reset
    ( set system colors )
    #0a6f .System/r DEO2
    #05cf .System/g DEO2
    #0caf .System/b DEO2

    ( configure screen device )
    ;on-frame .Screen/vector DEO2
    ;brush .Screen/addr DEO2
BRK

@on-frame
    ( read mouse coordinates )
    ( and use as screen coordinates )
    .Mouse/x DEI2 .Screen/x DEO2
    .Mouse/y DEI2 .Screen/y DEO2

    ( read mouse state and compare for left click )
    .Mouse/state DEI
    #01 EQU ,&draw JCN ( jump when mouse is pressed )
    BRK

    &draw ( draw sprite: 4-fg, 5-color1 and alpha )
    #45 .Screen/sprite DEO
BRK

( sprite data )
@brush 3e7e ffff ffff 7e3c
```