LULZCODE

This page documents everything we added to LOLCODE to make LULZCODE.

API

LULZCODE implements API-level checking (as a warning). Current API-level is 2600. All lulzcode files should start with HAI 2600 and end with KTHXBYE

File extensions

To work with the atom extensions (code highlighting, completion, etc) LULZCODE files should end with .lulz extensions.

FRENDs

For code maintainability and portability, FREND has been added to LULZCODE. It is functionally equivalent to #include in c. FREND can be included recursively. However, this is not recommended as the same file may be included multiple times. It is a best practice only to make FRENDs at the top level LULZCODE file.

  • FREND "path"

TROLL

  • TROLL "<path>" - Execute another LULZCODE file. The LULZCODE pipeline can be memory intensive and it is not recommended to do this recursively as a new LULZCODE context is established for each TROLL

LETR

One type was added to LULZCODE: LETR in addition to YARN, NOOB, TROOF, etc.

LETR is a single character (char in C).

Example, this does an ascii conversion:

I HAS A var ITZ 65
VISIBLE MAEK var A LETR

YARN Manipulation

  • KOUNT "<YARN>": Calculates YARN length.
  • GNAW "<YARN>" <start> <end>: Substring of a YARN
  • CUT "<YARN>" <index>: Gets the ascii decimal value of a single LETR in a YARN
  • YO "<YARN>" <index> "<YARN>": Overwrites part of a YARN

Example:

BTW Prints 11
VISIBLE KOUNT "Hello World"

BTW Returns llo
GNAW "Hello World" 2 4

BTW Returns 111
VISIBLE CUT "Hello World" 4 

BTW Prints l
VISIBLE MAEK CUT "Hello World" 4 A LETR

BTW Prints Hello Badge
I HAS A text ITZ "Hello World!"
text R YO text 6 "Badge"

BUKKITS

LULZCODE uses LOLCODE BUKKITs but extends slightly.

  • HOW MANY IN <BUKKIT> - Counts the items in a BUKKIT

Color

Colors are shared between LEDs and LCD. The LEDs use 32bit or discreet R, G, B values whereas the LCD uses 565 (16-bit) colors. These functions help with conversion between various colors.

  • ROYGEEBIFF2 <r> <g> <b> - Convert an RGB value to 565 color (for LCD) where r, g, b are 0 to 255
  • HSSSVEE2 <h> <s> <v> - Convert discreet hue saturation and value to 565 color (for LCD) where h, s, v are 0 to 255
  • HSSSVEE2BLINKY <h> <s> <v> - Convert discreet hue saturation and value to single 24-bit RGB value (for LEDs) where h, s, v are 0 to 255

LCD Graphics

There are a couple constants available to help with graphics.

  • HOW WIDE - returns integer containing width in pixels of the display
  • HOW TALL - returns integer containing height in pixels of the display

Screen buffer

All graphics commands like SHOUT and MEOW and STRAIGHT draw to a screen buffer. The LOLOLOL command must be used to push the buffer to the screen.

Text

  • CRAYON <color> - Set the current font color. Use ROYGEEBIFF2 to generate a 565 color.
  • SHOUT "<value>" - Set the current font. Valid values:SMALL, MEDIUM, LARGE, LUDICROUS
  • HOW SPREAD "<YARN>" - Measure text width of YARN using current font
  • HOW BIG "<YARN>" - Measure text height of YARN using current font
  • LAZER <x> <y> - Move the cursor to X, Y coordinates. Note: Cursor is moved relative to current font
  • INSIDEZ <x> <y> <width> <height> - Set the cursor area (for word wrapping and clipping purposes)
  • MEOW "<text>" - Print text to screen using current font at the current cursor location

Example:

BTW Set current font color to red
CRAYON ROYGEEBIFF2 255 0 0
BTW Use a large font
SHOUT "LARGE"
BTW Move cursor to origin
LAZER 0 0
BTW Print
MEOW "Hello World"
BTW Push screen buffer
LOLOLOL

Shapes

  • ALL <color> - Fill the screen with a color
  • DOT <x> <y> <color> - Draw a single pixel with a color
  • ROUND <x> <y> <radius> <color> - Draw circle
  • CATINAROUND <x> <y> <radius> <color> - filled circle
  • BOX <x> <y> <w> <h> <color> - Draw a rectangle
  • CATINABOX <x> <y> <w> <h> <color> - Draw a filled rectangle
  • STRAIGHT <x1> <y1> <x2> <y2> <color> - Draw a line between x1,y1 and x2,y2 with a color

Graphics

  • KATNIP "<path_to_file>" <x> <y> <w> <h> - Draw a raw file from SD card at x, y with width and height

Example: 

BTW Draw an image at 0,0 with 100x100 dimensions then push the buffer
KATNIP "/sdcard/gfx/image.raw" 0 0 100 100
LOLOLOL

LEDs

Like the LCD, LEDs are buffered. After setting color values for LEDs, be sure to push the LED buffer with LOLOL. Note: The Eye LED is not buffered.

  • BLINK <index> <color> - Set a single LED at index (0-30) to a 24-bit RGB value
  • BLINK <index> <r> <g> <b> - set a single LED at index (0-30) to discreet R G B values
  • BLINKIES <color> - Set all LEDs to a 24-bit RGB value
  • BLINKIES <r> <g> <b> - Set all LEDs to discreet R G B values
  • LOLOL - Push LED buffer
  • WINK <value> - Set the EYE LED to a value (0-255).
  BTW Cycle all LEDs by hue
  IM IN YR loop UPPIN YR i TIL BOTH SAEM i AN 255
    I HAS A rgb ITZ HSSSVEE2BLINKY i 255 255
    BLINKIES rgb
    VISIBLE i
    LOLOL

    PAWS 50
  IM OUTTA YR loop

Bling!

Use RICK ROLL WIT <path> <pattern> <loop> to play raw files. Note: this bypasses the screen buffer and is streamed directly to the screen to get maximum FPS. Any other drawing operations will have odd side effects.

  • <path> - Path to to raw file to play
  • <pattern> - Integer value for LED pattern to run along with bling
  • <loop> - WIN to loop. FAIL to play once. Looping allows the user to quit with the LEFT button. If looping is disabled, user input is ignored and it will quit at the end of the animation.
value LED Pattern Description
0 None
1 Hue cycle
2 Polar (accelerometer)
3 Sparkle
4 Double Sweep
5 Flames
6 Bouncing
7 Chasing Red
8 Chasing Green
9 Chasing Blue
10 Chasing Yellow
11 Kitt
12 Rainbow
13 Roller Coaster Red
14 Roller Coaster Green
15 Roller Coaster Blue
16 Roller Coaster Yellow
17 Red, Green, Blue, Yellow sweep

These are also defined in led_patterns.lol

Example:

BTW Play rick roll with roller coaster yellow LED pattern once
RICK ROLL WIT "/sdcard/bling/rick.raw" led_pattern_roller_coaster_yellow FAIL

Buttons

There are 7 buttons available on the badge. The automatic screen inversion properly flips the buttons as well. U, D, L, R buttons are left of the screen. A and B buttons are below the screen. And the action button is to the right of the screen.

Button state is managed as a single 8-bit value with bitmasks for each button. The mask is not automatically cleared in all cases.

  • KITTEH - Get the current button state (bitmask)
  • BAD KITTEH - Clear button state
  • POUNCE - Block the badge until a button is pressed. Note: This may return early if there was a timeout waiting. Check the button value with KITTEH to ensure something was actually pressed and a timeout did not occur.
  • WHATSUP - Is up pressed?
  • WHATSDOWN - Is down pressed?
  • ISLEFF - Is left pressed?
  • ISRIGHT - Is right pressed?
  • WATTA - Is A pressed?
  • WATTB - Is B pressed?
  • ISGO - Is start pressed?

User Input

Due to performance issues, user input was written in C and wrapped in LULZCODE. Use the MEOMIX command to return a string from the user up to 8 characters. This function will block until the user returns.

Format:

MEOWMIX <prompt> <Initial Value> <Max Length>

Example:

MEOMIX "Name" "Bender" 8

Badge State

  • OHIMEMBER "<key>" - Gets a value stored at "key"
  • MEMBER "<key>" "<value>" - Sets a value stored at key

The following keys are available. Not all are writeable

Key Description Read Write
name Player name X X
botnet_points Defense rating X -
botnet_experience Experience X -
botnet_level Player level X -
botnet_name Name of botnet player is in X -
voltage Battery voltage X -
brightness Screen / LED level X X
score_pong Current pong high score X -
score_ski Current ski free high score X X

Globals

Globals can be set and shared between LULZCODE contexts. Globals are not persisted and only stored as long as the badge has power.

  • MAH "<key>" "<value>" - Set a global
  • TEH "<key>" - Get a global value (if it exists)

Constants

  • VERSHUN - returns a string containing current firmware version
  • WHOAMI? - returns integer of the unique serial number of the badge

Random values

CRAZY GO NUTS <max> - Generate a random value between >= 0 and < max.

Accelerometer

  • SIDEWAYZ - Get accelerometer X value that is side to side relative to body.
  • UPWAYZ - Get accelerometer Y value that is up / down relative to body.
  • OUTWAYZ - Get accelerometer Z value that is outward from body.
  • TILTZ - Get angle of X/Y values with 0 degrees being the user's head and 180 degrees being the user's feet. 90/270s degrees are tilting right and left.

I2C

Note 7-bit addresses are used and will be shifted by one and R/W bit set per the standard. If your I2C slave is non-standard tough luck.

  • NOMS <7-bit address> <register> <byte> Write a byte to a register
  • NOMS <7-bit address> <byte> Write a byte to an address
  • NOM <7-bit address> <register> Read a single byte from a register

System Calls

Specific functions in the badge have been exposed as system calls.

  • SYSTUM "<call>" - Make a system call
call Description
ABOUT Show about screen
ADDON_START Start the background addon task
ADDON_STOP Stop the background addon task
INTERRUPTS_ON Allow UI interruptions
INTERRUPTS_OFF Do not allow UI interruptions
BOTNET Run botnet UI
NAME Pick name
SHOUTS Show shouts screen
SKI Run ski free game
STATE_RESET Factor reset badge state
TILT_ON Enable screen tilt
TILT_OFF Disable screen tilt
TIME Show current time GUI

Peers

  • BADGEZ? - Get a BUKKIT of current peers

Time

  • TIX - Get the current time in milliseconds
  • PAWS <ms> - Delay execution for x milliseconds

Files

  • DAB "<path>" - Get a BUKKIT of file paths in a given path

See chip8.lulz for an example

CHIP-8

  • NACHOS "<path>" - Run a CHIP-8 or Super CHIP-8

Unlocks

  • CHEEZBURGER "<code>" - Validate an unlock code
  • L33T - Get the unlock state as an integer, unlock values are stored as a bitmask

Token Reference

Token Description
ALL Fill screen with a color
BAD KITTEH Clear button state
BADGEZ? Get peer badges
BLINK Set single LED
BLINKIES Set all LEDs
BOX Draw a Rectangle
CATINABOX Draw a filled rectangle
CATINAROUND Circle, filled
CHEEZBURGER Validate Unlock
CRAYON
CRAZY GO NUTS Random number
CUT String char at index
DAB List of files in a directory
DOT Draw Pixel
FREND Include another LULZCODE file
GNAW Substring
HOW BIG Calculate text height */
HOW MANY IN Count BUKKIT items
HOW SPREAD Calculate text width
HOW TALL LCD Height
HOW WIDE LCD Width
HSSSVEE2 HSV to 565
HSSSVEE2BLINKY HSV to RGB
INSIDEZ Set the Cursor Area
ISGO Is start pressed?
ISLEFF Is left pressed?
ISRIGHT Is right pressed?
KATNIP Draw bitmap (raw file)
KITTEH Button state
KOUNT String length
L33T Get unlock state
LAZER Move the cursor
LETR Char type
LOLOL Push LED buffer
LOLOLOL Push screen buffer
MAH Global Set
MEMBER Store a setting value
MEOW Print
MEOWMIX Get user input
NACHOS Run CHIP8 File
NOM I2C read byte
NOMS I2C write byte
OHIMEMBER Get a setting value
OUTWAYZ Accelerometer Y value
PAWS Delay
POUNCE Wait for button
RICK ROLL WIT Play Bling
ROUND Circle, empty
ROYGEEBIF2 RGB to 565
SHOUT Set font size
SIDEWAYZ Accelerometer X value
STRAIGHT Draw a Line
SYSTUM System call
TEH Global Get
TILTZ Get current angle in degree of X/Y axis
TIX Get time millis
TROLL Run file
UPWAYZ Accelerometer Z value
VERSHUN Current firmware version
WATTA Is A pressed?
WATTB Is B pressed?
WHATSDOWN Is down pressed?
WHATSUP Is up pressed?
WHOAMI? Get unique id
WINK Eye led
YO String set char at index