Vito Van

Porting Lisp Game to the Web

Vito Van — Mon, 05 Jun 2023 15:28:05 +0000

2023/06

TL;DR

Here is a game written in Common Lisp and ported to the web:

It's an action game in which you can control the blue dot with your keyboard to create music and avoid colliding with other dots.

You can play it in your browser:

or download it for Linux, macOS, and Windows.

Motivation

I made a game, and I sent it to Jack.

Jack asked: "How to run it?"

I thought Jack was stupid, so I ignored him and sent it to Emma.

Emma said: "It cannot be opened."

I was like: "Really?"

It turns out Microsoft and Apple were sitting between me and my friends, saying:

"No, you are not opening this, because Vito didn't pay."

Like this:

or this:

I hate this.

"Who watches the watchmen?" I don't know.

I just want to share my game without making deal with the OS police. Since I don't have the resources to fight them, I have to find a workaround. So I tried porting this game to the web.

Hopefully, we won't encounter the web police too soon.

Exploration

to Lisp

The first step should be running Lisp in the browser.

Today we can run Linux and Windows inside a browser, running a Lisp system is just a piece of cake, compared to an operating system.

I found the following two approaches:

I didn't list everything here, you could find more. I also didn't list the approach of (Lisp (inside an emulated x86 (inside a browser))), because it sounds too aggressive.

The point is the work could be done or has already been done.

So, what now?

to Game

We need to be able to provide an interactive multimedia experience to the players, that is:

to respond to the user inputs
to present dynamic graphics
to play music and sounds

Lisp the great and powerful itself won't do any good to that, unless you cut the graphic and sound parts, and decide to make a text-based game.

Compiling SDL2 and Cairo

I was using SDL2 and Cairo to provide the interactive multimedia experience on the desktop, with the assistance of cl-sdl2 and cl-cairo2.

How do I use them in the browser?

Maybe we could try WebAssembly.

SDL2 is WebAssembly-ready since the last year.

And I spent some time on Cairo and compiled Cairo into WebAssembly.

Try to Use SDL2 and Cairo With Lisp

Now we know that we can use SDL2 and Cairo in the browser, but how?

On the desktop, we use cl-sdl2 and cl-cairo2, which is CFFI → load-shared-object → dlopen under the hood.

How do we do it in WebAssembly? Or, is it possible?

It is possible.

Dynamic Linking and dlopen in WebAssembly is not a problem, the problem is to make CFFI work with it.

No, not with it, with the Lisp implementation we chose.

CFFI depends on ASDF and libffi. libffi had its WebAssembly support earlier this year, so we only need to focus on ASDF.

Only one of the above Lisps was officially supported by ASDF, which is ECL. So, to save time, we should stick to ECL and see if we can make any progress.

I paused.

I was intimidated by ECL when I was young and fragile.

It was a long long time ago, one day morning, I loaded my project into ECL and tried to generate a standalone application. It took a thousand years to compile and end up with some weird ASDF-related error that I still can't solve today. I also failed to upgrade ASDF for ECL after many hours of scrambling. I must say this was solely because of my stupidity, ECL is great, I am just too dumb.

And I paused.

I was so frightened by this task, so I asked Daniel, whose name will be printed out along with the word "Copyright" when you were starting ECL, like this:

ECL (Embeddable Common-Lisp) 21.2.1 (git:6af4b3e51f80d569d88f0e8a4782b21c8b04970e)
Copyright (C) 1984 Taiichi Yuasa and Masami Hagiya
Copyright (C) 1993 Giuseppe Attardi
Copyright (C) 2013 Juan J. Garcia-Ripoll
Copyright (C) 2018 Daniel Kochmanski ;; <---- this Daniel
Copyright (C) 2021 Daniel Kochmanski and Marius Gerbershagen
ECL is free software, and you are welcome to redistribute it
under certain conditions; see file 'Copyright' for details.
Type :h for Help.
Top level.
>

And Daniel said: "go for it!"

Then I went for it.

That's when the nightmare began. It turns out that making ASDF work with ECL in the browser is way more difficult than on the desktop.

I was drowned in the sea of ECL source code; suffocated on the mountain of Emscripten reference; and lost in the forest of 13987 lines of asdf.lisp.

Although Marius Gerbershagen (another ECL maintainer, also listed in the ECL copyright notice) pointed out another path (static linking) for me to achieve the goal, I still haven't made it.

My intelligence was heavily questioned.

I felt sad and paused again.

Until one day.

I was talking with Jack on the phone:

"Now, press the return key."

"Where is the return key?"

"It's on your keyboard, damn! The one above shift!"

"Oh, you mean Enter?"

"......"

Jack was using a Windows PC, and the letter on his keycap is "Enter".

I was using a MacBook, it is "return".

So: If my game were running in the browser one day, how do I know the player's operating system?

Did you just say navigator.userAgent? navigator.platform?

Yeah, that's it!

Wait, what language is that? JavaScript?

No, shit.

If Using JavaScript Were Inevitable

It seems to be it.

Running in the browser, you have to deal with the browser.

Not only to detect the operating system but also:

to detect the browser's preferred sampleRate of AudioContext
to get the parameter of the URL, like: ?name=Jack
to get the current window size
to redirect the page to my cool web blog
to show an evil alert
...

With C, we can call JavaScript like this:

#include <emscripten.h>

EM_JS(void, call_alert, (), {
  alert('hello world!');
  throw 'all done';
});

int main() {
  call_alert();
  return 0;
}

With Lisp, how?

We can:

write JavaScript in a C function
expose that the C function
defcfun in Lisp with CFFI to use it

If the above feels too complicated, we can also use SFFI from ECL, to (write JavaScript code (inside C code (inside Lisp code))), maybe like this:

(defun alert (x)
  (ffi:clines "#include <emscripten.h>")
  (ffi:c-inline (x) (:cstring) :void "
        EM_JS(void, call_alert, (), {
          alert('hello world!');
          throw 'all done';
        });
        call_alert(#0);
"))

Beautiful, right? I wouldn't dare to touch things like that, it's holy and sacred, and it should be reserved for sainthood.

Now let's forget the SFFI approach and sort out our tasks:

make WASM Dynamic Linking, ASDF, CFFI, and ECL work,

or make ASDF, CFFI, WASM ECL statically linked with Cairo working
write an unknown amount of JavaScript in C and wrap them in CFFI
compile all those pieces of spaghetti code into WebAssembly
press our palms together and pray

I am only good at the last one.

Using SDL2 and Cairo With Lisp in JSCL

using JavaScript were inevitable
using SDL2 and Cairo with WASM Lisp were hard to achieve

then, why don't we

use a JavaScript-powered Lisp to interact with JavaScript, then
use SDL2, Cairo WASM exported functions within JavaScript, then
wrap the JavaScript call with some Lisp code?

Let's try JSCL, to call JavaScript within Lisp:

(#j:alert "this is an alert")

If we exported SDL_GetTicks via emscripten, we could call it in Lisp, like:

(#j:_SDL_GetTicks)

Convenient, right?

Now, let's sort out our tasks again:

export all the needed functions via emscripten
wrap them a little for ease of use
done

Oh, really?

Yes, really.

I exported all the frequently used SDL2 and Cairo functions, then wrapped them with some Lisp code, and then I can call them as if I were on the desktop operating system:

(defun draw-blade (&optional (degree 0))
  (c:save)
  (c:translate 300 170)
  (c:rotate (* degree (/ pi 180)))
  (c:move-to 0 -15)
  (c:line-to 0 -100)
  (c:curve-to 0 -110 100 -65 15 0)
  (c:stroke-preserve)

  (c:set-source-rgba (/ 12 255) (/ 55 255) (/ 132 255) 0.1)
  (c:fill-path)
  (c:restore))

You can try it yourself with this link, the source code is here.

As I clicked on the blue circle in the upper right corner, a gentle breeze carrying the scent of freshly cut grass wafted out of the screen. It was then that I knew it was time to call it a day.

What Now?

With the availability of Lisp in the browser, along with SDL2 and Cairo, the possibilities for interesting projects are endless.

The day-to-day development could happen on the desktop with SBCL + SLIME enabled to get an interactive programming experience. When done, compile everything to WebAssembly + JavaScript, and publish the result online, then you have an application that supports Linux, macOS, Windows, and the web browser!

But, JSCL is far from complete.

In the perfect new world, we should expect:

JSCL (or any other JavaScript Lisp) is complete, like ANSI complete, or
ECL (or any other complete Lisp) and the surrounding ecosystem function seamlessly in the browser

If you're interested, then go for it!

And we don't need a complete Lisp to have fun, right?

I can't wait to see what you are going to make.

;-)

Jack's Ass

Vito Van — Sun, 19 Feb 2023 09:38:19 +0000

2023/02

Jack is my friend, he had hemorrhoids.

Hemorrhoid is one of the experiences which could be legitimately called: "the pain in the ass". Something grows in the ass and causes pain.

1

One day in a coffee shop, Jack and I were chattering.

I said: "Damn! Lisp is so cool! I wish I could have known it earlier!"

Then Jack said: "Is it cool enough to solve my ass problem?"

That was a medical problem, and I ain't no medic. Although I deeply know that Lisp is cool enough to solve it, I choose to hold my impulse and asked:

"What did your doctor say?"

"He said this is not curable by any known medicine. Once it is there, it is there. The only way to solve this problem is to cut it out. I said no."

"And?"

"And I'm in pain! I can't sit for too long, otherwise, my ass will blow up."

"Can't you just keep standing?"

"That will hurt my knees! I have tried to set a bunch of timers, but they were a mess."

"OK, that's easy, Lisp can do it, I assure you," I said.

Then Jack paid for the coffee, and I sent him the software to cure his ass by the end of the day. It's just a Pomodoro timer that reminds him to stand up every 25 minutes, written in Lisp with SDL2 and Cairo Graphics.

I also have written a detailed manual to explain how to install the software with SBCL, SDL2, Cairo Graphics, and some other dependencies. Anyone with some basic computer knowledge could manage to install it.

2

A month later, I met Jack in the same coffee shop.

"How's your ass?" I asked.

"The hemorrhoids were gone."

"See? I told you, Lisp is cool!"

"No, I let the doctor cut my ass."

"Oh, Why's that?"

"I spent a whole day sitting in front of the computer to install SDL2, SDL_Mixer, SDL_Image, Cairo, SBCL, Quicklisp, and many other shits to get your shitty software working. Suddenly, a huge pain came from my ass. When I stood up, blood was all over the chair. Then I called the ambulance."

"No! Uh..."

3

That night, I couldn't sleep.

Jack's wounded ass is all my fault.

So I decided to never ask non-wizard users to install any dependencies again.

After uncountable days and nights sitting in front of the computer, I made it.

Suddenly, a huge pain came from my ass.

4

If you have any interest, here is the ass-curing software: Focolizzare.

And here is the framework used to build it: CALM.

ख़िंलेर्मोर्ना - xinlermorna

Vito Van — Sat, 28 Sep 2019 00:53:58 +0000

2019/09, revision: 2019/10

By: la vitno, Version: ख़िं 0.6 , PDF: xinlermorna-V0.6.pdf

Devanagari Orthography for Lojban based on Hindi pronunciation

Tables

Consonants

Note: all the inherent vowels /ə/ are reserved as y in Lojban, suppressing is not allowed without being explicitly marked as such (with ्) or being the last letter of word.

Latin	देवनागरी
c	श
j	झ़
s	स
z	ष़ *
f	फ़
v	व
x	ख़
'	ह
r	र
l	ल
n	न
m	म
b	ब
d	द
g	ग
k	क
p	प
t	त
dj	ज
tc	च
dz	ज़ *
ts	च़

* letter ष़ /ɭə/ is assigned the value /zə/

* letter ज़ /zə/ is assigned the value /ʣə/

Vowels

Latin	देवनागरी (Indepdt. Form)	देवनागरी (Diacritic Form)	देवनागरी (Diacritic Form with 'k/क')
a	आ	ा	का
e	ए	े	के
i	इ	ि	कि
o	ओ	ो	को
u	उ	ु	कु
y	अ	(inherent)	क

Diphthongs

When used alone, diphthongs can be written as Vowel Independent Form or Diphthong Independent Form, they are All Accepted

When i (इ) is written as first letter in diphthongs, the following vowel should always be written as the Independent Form (e.g. आ instead of the Diacritic Form ा). By this way, we are able to seperate words start with kai... (काि...) the ones start with kia... (किआ...). If not, we will get kai... (काि...) and kia... (किा...), which is hard to tell the differences by a normal human.

Latin	देवनागरी (Vowel Indepdt. Form)	देवनागरी (Diphthong Indepdt. Form)	देवनागरी (Diacritic Form)	देवनागरी (Diacritic Form with 'k/क')
ai	आइ	आि	ाि	काि
ei	एइ	एि	ेि	केि *
oi	ओइ	ओि	ोि	कोि
au	आउ	आु	ाु	काु
ia	इआ	इा	िआ	किआ
ie	इए	इे	िए	किए
ii	इइ	ई	ी	की
io	इओ	इो	िओ	किओ
iu	इउ	इु	िउ	किउ
ua	उआ	उा	ुा	कुा
ue	उए	उे	ुे	कुे
ui	उइ	उि	ुि	कुि
uo	उओ	उो	ुो	कुो
uu	उउ	ऊ	ू	कू
iy	इअ	इअ	िअ	किअ
uy	उअ	उअ	ुअ	कुअ

* When kei is written in as केि, it may not be rendered properly by every font. Hence, Devanagari Vowel ai (ऐ / ै) is also acceptable to be used as ei, so kei can also be written as कै.

Conjunct Consonants

Consonants lacking a vowel in between them MUST physically join together as a conjunct consonant.

Latin	देवनागरी (GOOD)	देवनागरी (BAD)
lojban	लोझ़्बान	लोझ़बान = lojyban
kanla	कान्ला	कानला = kanyla
ckaji	श्काझ़ि	शकाझ़ि = cykaji
klama	क्लामा	कलामा = kylama
bajra	बाझ़्रा	बाझ़रा = bajyra

Anusvara

When consonant n is preceded with a vowel and followed with a consonant (e.g. kanla), you can use a diacritic dot (which is called Anusvara: ं) to mark it instead of the independent form n (न), write with Anusvara or Independent Form are Both Accepted

latin	देवनागरी (Indepdt. Form)	देवनागरी (Anusvara)
kanla	कान्ला	कांला
condi	शोन्दि	शोंदि
panci	पान्शि	पांशि

Text Examples

Name	Text Sample
Standard Orthography	pu ze'u se djuno lei ze'u renvi gi'e se jijnu ca le temci be le nu le dzena ca jmive vau fa le du'u le bradi be le la tlunranan. ba klama ri
xinlermorna	पु ष़ेहु से जुनो लै ष़ेहु रेंवि गिहे से झ़िझ़्नु शा ले तेम्शि बे ले नु ले ज़ेना शा झ़्मिवे वाु फ़ा ले दुहु ले ब्रादि बे ले ला त्लुंरानां· बा क्लामा रि

* Text Sample Source comes from "How the enemy came to Thlunrana": https://jbotcan.org/lojban/en/how-the-enemy-came-to-thlunrana/

Pictures with Different Fonts

* Jaldi https://fonts.google.com/specimen/Jaldi

* Hind https://fonts.google.com/specimen/Hind

* Martel https://fonts.google.com/specimen/Martel

You can try it with the xinlermorna transliteration tool.

Dinosaur and Lisp

Vito Van — Mon, 10 Jun 2019 05:58:35 +0000

2016/08

Dinosaur is old enough, as well as Lisp, they may like each other. When I am talking about dinosaur here, I mean the dinosaur hiding in Google Chrome, it shows up when "There is no Internet connection".

What's This All about?

This is about writing some code in Common Lisp, which is capable of playing the Chrome Dinosaur Game itself (no Deep Learning involved).

What Do We Have in Hand?

When I'm trying to do this, I'm sitting in front of a computer with Linux installed, and of course it has a screen monitor. So, it is easy to set up a Common Lisp environment, here is my list:

A Linux Machine (with screen monitor connected, to watch the dinosaur jump)
SBCL (I'm using 1.3.4 now, higher may be better)
Chromium or Google Chrome (I'm using Chromium 52.0.2743.116 now)

I also installed Emacs with SLIME to play around with Lisp, you can have any other editor instead of this.

Well, all set, let's start.

the Eyes

It's easy for us to recognize the dinosaur, a tiny cute creature with two short legs running on our screen, but it's not easy for Lisp. We can see the screen with our eyes, Lisp can't, so we gonna write some code to read the screen, and find the dinosaur.

Read the Screen

After searching the web, I found that there's no concept of Screen in Common Lisp. Actually, I found this:

... There are only rudimentary libraries for manipulating strings, and almost none for talking to the operating system. For historical reasons, Common Lisp tries to pretend that the OS doesn't exist ...

- Being Popular (Section 6)

"the OS doesn't exist", what the ... , I must be lost my mind to choose Common Lisp.

But since that article is written in May 2001, it's been 15 years later, things must have been changed a lot. After digging around again, I found something very useful:

CFFI, the Common Foreign Function Interface, and this means we can call any C (and not only) library from Lisp.
CLX, an implementation of the X Window System protocol to Lisp, and this means we can take control of the whole X Window System, of course we can read the screen! (if you are using OS X or Windows, this may be a little tricky)
burgled-batteries, a Python-Lisp bridge, and this means we can call any Python functions seamlessly in Common Lisp.

Actually, there's plenty of libraries out there today, you can basically do anything you want in Common Lisp, the OS does exist! Hooray~

Finding Dinosaur

After reading the CLX Manual, we found that we can use function get-raw-image to directly get the image data from the specific region. Then what? Let's find out what we need to find the dinosaur:

What's in my mind now? well, the dinosaur is keep running and running, we need to keep read the screen and find it's position. Yah, let's do it.
OK, I am reading the screen every 0.1 seconds, and now I need to write some code to match the shape pattern of the dinosaur.
Shape Matching, sounds thrilling, I've never been there before, then after another round of searching, I found some papers:
I started to read, the papers are obscure, Mm... they are talking about math, Mm... I don't recognize this mathematical formula, Mm...
I have to take a break, let's play the Dinosaur Game.
Oh, my! The dinosaur never moved! It is just keep dangling it's tiny legs and pretending: "Yah, I am running, I am running".
This is the ultimate humiliation to my extraordinary human intelligence.

But I've been over it almost immediately, cause I have no need to read those obscure papers anymore, phew~

Then, what's left?

All we have to do about this dinosaur now, is to determine the current state of our dinosaur: STANDing / JUMPing / BENDing (yah, it can bend, try the down key).

Since the dinosaur never really moved forward or back, we can take screenshots of the different postures of our dinosaur, then open them in GIMP to get the corresponding position points, we can do this in our code:

(defvar *dino-standing-points* '((207 238) (242 223)))
(defvar *dino-bending-points* '((209 240) (262 243)))

After we have these points, we can capture the image data of current screen, then get the colors of those specific dots, and determine if the color equals to the color of dinosaur, if all *dino-standing-points* matched, then it is standing, as well as *dino-bending-points*, otherwise it is jumping.

But after playing a while, we know that the color of dinosaur is changing between day and night, so we should have a function to get the changing color of the dinosaur. Since the dinosaur is jumping or bending, it's much easier to locate the color picking point of background, then we can determine the state of the dinosaur by using the background color: If all the color of *dino-standing-points* does not match the background color, then it is standing.

Dinosaur Finding Problem solved.

Cactuses and Birds

These front cactuses and birds could kill our dinosaur. So we have to detect them and take an action of JUMP / BEND or just STAND still (the time of action also matters). We can get the image data in front of the dinosaur, and check if there is a cactus or bird:

The search area could be narrowed down to a 500x35 square, and the position of this square is fixed, we can easily get it from a full screenshot with GIMP. Then we can write something like this:

;; the block search square (x y weight height)
(defvar *block-search-square* '(265 220 500 35))

And when we get the image data of this area, then compare the background color with each pixel, if it does not match, then the cactus or bird is found!

When we comparing the pixels, we choose to scan the image from left/top to right/bottom, then we will get the top/left position of the front cactus or bird.

Here are the cactuses and birds I collected (some kind of cactuses may be missed):

Actually, the types of cactus make nothing different, no matter it is tall or short, wide or narrow, it will be successfully passed if we jump at the appropriate time. But for the birds, we should separate them out by LOW / MIDDLE / HIGH, when it is LOW type bird, we JUMP; when it is MIDDLE type bird, we BEND, when it is HIGH type bird, we do nothing.

From the image above, we can see that those birds in different types have unique y-coordinates among themselves and cactuses, we can just tell which kind of bird it is by the value of it's y-coordinate.

Actually, all we need is the unique y-coordinate of the MIDDLE type bird, cause we can treat the LOW type bird the same as cactuses, and the HIGH type bird, we just pretend they never exist (cause we gonna ignore them). So, all we need is:

;; the y of middle flying bird
(defvar *middle-bird-y* 220)

Cactuses and Birds Detecting Problem solved.

Now, here's what we got:

We know the state of our dinosaur: STANDing / BENDing / JUMPing.
We know the position of the front cactus or bird.
We know what action we should take: JUMP / BEND or NOTHING.

What's left?

It's HOW and WHEN, how to perform the JUMP or BEND action, and when to perform that action. Let's discuss them next.

Dancing Around

HOW?

To jump or bend our dinosaur, we need to simulate the key press event of SPACE (or UP) and DOWN.

The X Window System must have a way to simulate key press event, and also CLX is an implementation of the X Window System protocol to Lisp, it means we have a way to simulate key press event as well. Once we figure out how, we'll be able to control the dinosaur.

After reading the CLX Manual, we found a section called: Event and Input, it's all about events manipulating, we may use them. But after talking with some awesome fellas on IRC, I learned that there's an extension of X Window System called XTEST, which is "a minimal set of client and server extensions required to completely test the X11 server with no user intervention", and it has an operation called XTestFakeInput which can be used to perform a fake key/mouse input as it is said by it's name.

And more luckily, this extension is already implemented in CLX, so we can directly call the function fake-key-event or fake-button-event, they should just work! What a good day~ Now we can call something like this in the REPL:

(xtest:fake-key-event display *space-keycode* t) ; key down
(xtest:fake-key-event display *space-keycode* nil) ; key up

Then the dinosaur jumped, :-D

WHEN?

We should start to jump when we getting close to the cactus or bird, but how close? 100px? or 200px? should we test all these values and find the best one? No, there's no one. We can't say "Hey tiny dino, you should jump when the distance between you and the cactus in front is less than 100px", because the speed is accelerating. Maybe 100px works pretty well when it is slow, but when the game speed up, the value should be far more than 100px.

So, it is speed related, huh~ Since we can get the coordinates of the front cactus, calculate the speed will be done by dividing the change of x-coordinate by time passed, we can collect all the speed value each time we read the screen, then get the average value. Then we should figure out something like this:

(defun jump? (distance speed)
    (<= (/ distance speed) 0.15))

This function jump? take two parameters: distance, which represent the distance between the dinosaur and the front cactus; speed , which represent the speed of the cactus. Then, (/ distance speed) will be the time left before cactus hit our dinosaur, 0.15 is the time we preserved for our dinosaur to take it's feet off the ground. So, this function means: If we the cactus will hit our dinosaur in 0.15 seconds, we jump, then at the time cactus comes, our dinosaur will be right up in the sky, cactus passed!

Then, we can read the screen 60 times per second, and call jump? in every screen reading action, to check if we should jump.

At Last

After playing around with all the code snippets in SLIME-REPL, seems all systems go:

Screen Reading, powered by get-raw-image
- Dinosaur State Checking (stand or bend or in the sky?)
- Game State Checking (game over or not)
- Cactuses and Birds Detection
Keyboard/Mouse Simulation, powered by fake-key-event and fake-button-event
- Dinosaur Controller (SPACE and DOWN key)
- Game Activation (click to active the game window)

Just do a little more clean up, we'll have a Common Lisp-powered Super Dinosaur~

Now, we won't go through the details of the code implementation, you can find them at the end of this page.

Before we go, I wanna say: Lisp is not the old fragile useless academic language, also, it's not any alien super power. It's a language, it works if you really touched it, and works great.

Video on YouTube:

https://youtu.be/PkzlJcKR4TI

Code on GitHub:

https://github.com/VitoVan/cl-dino

I am pretty new to Common Lisp, the code may be a little messy (although I tried not to be like that), it will be great if you can point out something inelegant for me, thanks!

License: GNU GPL v2.0

Discuss on HN: https://news.ycombinator.com/item?id=12351187

Related:

Japanese Translation