How does this work?
Welcome to the poetry machine! You can write poems, and they are also code!
In order to write something that works (showing something interesting on the screen) you need to understand a bit how the underlying platform works.
The emulator provided here is a Chip-8. This is an old virtual machine invented in the 70s and released in the BYTE magazine. You can find out more about it on Wikipedia.
The Chip-8 has only 35 instructions, and they are extremely easy to use and remember. Here, they all correspond to a "verb".
Just use the right verb in your sentence, and the corresponding insctruction will be executed.
Each time you make a new line, it'll correspond to a new instruction. In each line, the verb will try to find its arguments. Try to hide them properly so that the poem still keeps some style!
To see how numbers and verbs work together, read the sections "Numbers" and "Verbs".
For further explainations, try the video of the FOSDEM presentation.
Have fun, and share your work on Mastodon with the hashtag #codepoetry.
Titles and indexes
Some verbs require you to make reference to other parts of the code, for example to move from one part in memory to another, or to set the data pointer I.
To do that, you can name some parts of your code using a title.
A title is a sentence that won't be executed, but just gives a name to the code following it. You can make a title by putting dashes, equal signs, or underscores around it.
- This is a title -
== This one too ==
____I am also a title___
Titles can then be referenced in Indexed verbs by hiding a part of the title somewhere in the sentence. The biggest matching word is choosen. Example:
-- The Sea is bright --
Remember the sea.
In the given example, the verb "Remember" references the title "The Sea is bright" by using the word "sea". If the sentence had the word "bright" in it, that would have given the same result.
Numbers are expressed as hexadecimal nibbles, from 0 to F.
For example, the number 42 is 2A in hexadecimal, which is made of the nibbles 2 and A.
2 can be "Fire" and A can be "Spark", so 42 can be expressed as "Fire spark".
Other possibilities are "Red thunder", "Blazing bolt" or "Smell twice the Violet".
- Zero — 0
- Void, Death, Night, Blackhole, Zero, None, Empty(iness), Nothing(ness), Still(ness), Snow, Nowhere, False, Dark, Black
- One — 1
- Water, Tear, Sea, Yes, True, Truth, Everywhere, One, Once, First, Blue
- Two — 2
- Fire, Blaze, Burn, Two, Twice, Second(ary), Red
- Three — 3
- Vapor, Steam, Fog, Three, Third, Purple
- Four — 4
- Earth, Soil, Ground, Rocks, Four(th), Yellow
- Five — 5
- Mud, Oil, Glue, Tree, Leaf, Five, Fifth, Green
- Six — 6
- Lava, Volcano, Six(th), Orange
- Seven — 7
- Ceramic, Bowl, Seven(th), Grey, Gray
- Eight — 8
- Wind, Blow, Eight(h), Cyan
- Nine — 9
- Rain, Drop, Nine, Ninth, Marine
- Ten — A
- Thunder, Bolt, Spark, Ten(th), Violet
- Eleven — B
- Cloud, Sky, Eleven(th), Pink
- Twelve — C
- Sand, Desert, Snake, Twelve, Twelfth, Rose
- Thirteen — D
- River, Net, Fish, Thirteen(th), Azure(an)
- Fourteen — E
- Window, Glass, Transparent, Fourteen(th)
- Fifteen — F
- Life, Living, Complete, Full(y), Sun, Light, Planet, Fifteen(th), White
How to read this section
Verbs expect some parameters to be present anywhere inside the sentence (even before them).
The order of the parameters is important, because the verb will take them from first to last.
In definitions, the number of parameters each verb takes is indicated just after the verb, like this:
- Verb — X Y
- What the verb does with X and Y.
- Verb — X A B
- This verb takes a nibble X, then either only B (A will be zero) or AB
- Verb — Index
- This verb needs a title somewhere in its sentence.
There are three types of parameters : numbers, indexes and modifiers.
Numbers are made of nibbles (see the "Numbers" section of the dictionary). To form bigger numbers, you add multiple nibbles together. Some verbs accept small numbers (made of one nibble), or bigger numbers made of two nibbles. In the later case, the first nibble can be optional (its value will be zero if omitted). This kind of optional nibble is indicated with a dashed outline A in the verb definition.
For example, "Rose water" is the number "C1" while "Water" is the number "01" (with zero being the implict first nibble), and "Water rose" is the number "1C".
Indexes are used for movements and memory instructions. The verb tries to find the longest complete word in the sentence that matches one of the poem titles. Indexes cannot be expressed as numbers, only as plain text words.
Modifiers are used in only two verbs, "Skip, Evade" and "Jump". They specify whether the instruction should be "skip if equal" or "skip if different". They can be anywhere in the sentence, but need to be there, otherwise the verb can't be translated into a machine instruction. You can find the list of modifiers in the corresponding dictionary section.
- Quit — A
- Stop the program and return the value A.
- Clear —
- Clear the screen.
- Return, Leave —
- Return from a subroutine.
- Go — Index
- Go to the given title.
- Call, Hail — Index
- Call the subroutine at the given title.
- Skip, Evade — X A B (needs a modifier)
- Skip the next instruction unless the register X is equal/unequal to the number AB (when ommited, A is zero).
- Jump — X Y (needs a modifier)
- Jump over the next instruction unless the register X is equal/unequal to the register Y.
- Put, Take, Embrace — X A B
- Load the value AB in the register X.
- Add — X A B
- Add the value AB to the register X.
- Load — X Y
- Copy the value of register Y into the register X.
- Merge — X Y
- Set the register X = X OR Y.
- Ponder — X Y
- Set the register X = X AND Y.
- Cross — X Y
- Set the register X = X XOR Y.
- Stack — X Y
- Add the value of register Y to the register X (and set the carry flag in register F).
- Remove — X Y
- Substract the value of register Y from the register X (and set the borrow flag in register F).
- Turn — X
- Shift bits to the right in register X and through register F.
- Compare — X Y
- Substract the value of register X from the register Y, put the result in X, and set the borrow flag in register F.
- Rotate — X
- Shift bits to the left in register X and through register F.
- Remember — Index
- Set the pointer I to the position of the given title.
- Travel — Index
- Go to the given title + the value of register 0.
- Confuse — X A B
- Put a random value in register X masked by AB.
- Paint, Draw — X Y A
- Draw a sprite of height A on the screen at the position contained in registers X and Y, using pixel data currently indicated by pointer I.
- Listen — X
- Skip the next instruction if the key in register X is pressed.
- Ear — X
- Skip the next instruction if the key in register X is not pressed.
- Tick — X
- Put the current value of the delay timer in register X.
- Wait — X
- Wait for a key to be pressed and put it in register X.
- Rest — X
- Set the delay timer to the value of register X.
- Sing — X
- Set the sound timer to the value of register X.
- Remind — X
- Add the value of register X to the pointer I (and set overflow flag in register F).
- Write — X
- Set the pointer I to the position of the character representing the value in register X.
- Represent — X
- Transform the value in register X to decimal and save it at position I, I+1, I+2.
- Save — X
- Save the values of all registers from 0 to X at position I.
- Restore — X
- Load values into registers 0 to X from memory at position I.
Modifiers change the meaning of verbs which are based on equality/unequality.
- Equality modifiers
- Like(ly), Similar, Identical, Equal, Sometimes
- Unequalilty modifiers
- Unlike(ly), Different, Apart, Unequal, Always
You can write data if you make a sentence without any of the available verbs.
- No Verb — A B C D
- Write the given number ABCD here in memory.
About this project
This project was created by Jérôme Martin, who you can find:
It will be presented at FOSDEM 2020 on Sunday the 2nd at 9:30AM!
I hope you enjoy this. I can't wait to see the poems you're going to compose! Please share them with everyone on Mastodon with the hashtag #codepoetry.
All the code for this project is released under the terms of the GNU AGPLv3 license.
Copyright (c) 2020 Jérôme Martin — All Rights Reserved