%chess is an Urbit app which allows you to play chess with other Urbit users. It is a
fully-decentralized, peer-to-peer chess application.
The original %chess was made by Raymond E. Pasco for several reasons:
- To practice Hoon
- As a hobby project
- As a proof-of-concept that users could share software between ships using Urbit "desks" You can find his original repository for Urbit Chess here and his Urbit Chess Announcements page here.
Ray paused work on %chess in March 2021 due to personal reasons. In August 2021, Tlon released full-fledged software
distribution in an update to Arvo. ~finmep-lanteb updated %chess to work with this update as a broadly-visible
example of app distribution for Assembly 2021.
In September, 2022, ~bonbud-macryg, ~nordus-mocwyl, and ~rovmug-ticfyn began working on %chess in their spare
time for an Urbit Foundation bounty, which they completed in September, 2023.
%chess seeks to be a community sandbox for Urbit apps. As Urbit evolves, so too should %chess. %chess should seek
at all times to incorporate the most modern Urbit programming techniques. It should strive to provide well-documented,
clear, concise code that beginner Hoon coders can use as a reference.
Whether or not %chess meets all of these goals at any particular moment, they are the aspirations of the repo.
The "Chess Improvements Bounty" has been completed. Pharaoh has set the chess slaves free!
You can find %chess on Urbit using the App Search in Grid. Search for ~finmep-lanteb and you should see
%chess as an available app.
Alternatively, you can install from your ship's Terminal:
|install ~finmep-lanteb %chess
Below is a step-by-step guide for developing %chess and testing changes. This section assumes at least minor Urbit
development experience, i.e.:
- familiarity with Unix-based systems
- familiarity with git
- completion of at least some (preferably all) of Hoon School and App School
The above is not to say that people with no prior development experience are barred from contributing, just that this is
not a place to receive guided help. There are plenty of issues with %chess that need fixing, many of which are simple
and would be good "first-time" Urbit contributions.
See this guide on the Urbit developers portal for information on how to get the Urbit binaries and what sort of software may be useful for developing Urbit applications.
To spare you from the nightmare that is the JS development environment, %chess's build script is equipped to use
Docker; if you'd like to use Docker, make sure that you have it
installed and that your user account on your machine has sudo privileges.
(NOTE: Do not use the 'docker' group.)
If you are already in the nightmare that is the JS development environment and cannot wake up, you can build %chess
natively with Webpack.
This guide will cover both workflows regardless. For the Webpack build, we assume you have npm installed already.
git clone https://github.com/ashelkovnykov/urbit-chess.git
Check out the IDEA Hoon plugin if you want to work on Hoon with advanced language support!
Create a development ship of your choice:
./urbit -F zod
Create a %chess desk from inside your dev ship:
|new-desk %chess
Mount the %chess desk, so that we can push our updated code to it:
|mount %chess
Run the provided build script from /urbit-chess to compile the %chess frontend.
To run the Docker build, substitute the name of your dev ship using the -s option:
./bin/build.sh -s zod
To run the Webpack build you'll need to install Webpack and htmlWebpackPlugin if you don't have them already. cd to
/src/frontend and install Webpack and htmlWebpackPlugin:
npm install --save-dev webpack
npm install --save-dev html-webpack-plugin
(The --save-dev flag keeps %chess's dependency list clean for our collaborators using Docker.)
To run the build script with Webpack, add an -n flag like so:
./bin/build.sh -s zod -n
Run the provided installation script to copy the %chess backend files to the dev ship. Substitute the path to the pier
using the -p option and your pier's name using the -s option:
./bin/install.sh -p /home/user/Urbit/test-piers -s zod
Commit the changes from inside your dev ship:
|commit %chess
Next, tell the fake ship to install the app:
|install our %chess
This is only necessary the first time you install %chess on a fake ship. If you're updating the files on a ship which
already has %chess installed, just committing the new files is enough.
The dev ship is now awaiting the frontend files to link to the app. Installation is not complete until these files are
provided. Login to your dev ship through your browser (the URL at which the ship's interface is running is posted on
launch; it should look something like http://localhost:8080). Navigate to the docket glob interface (e.g.
http://localhost:8080/docket/upload). Follow the instructions on the page to upload the frontend files to your dev
ship.
Once globbing is completed, you can return to Landscape on the dev ship and see that %chess is installed.
Google Chrome and Chromium-based browsers have a tough time clearing the cache and picking up changes made to the frontend. If you're developing the frontend, it's recommended to use Firefox for final testing.
Once installed, you need to publish %chess so that other dev ships on your computer will be able to find it:
:treaty|publish %chess
Now, any other fake ships running on your computer will be able to install %chess through Landscape, just like they
would on the real network. Usually, though, it's more convenient to have them install through the command line:
|install ~zod %chess
Appearing in alphabetical order of @p:
~bonbud-macryg- @bonbud-macryg~datder-sonnet- Tom Holford, @tomholford~finmep-lanteb- Alex Shelkovnykov, @ashelkovnykov,~walbex~nordus-mocwyl- @brbenji~rovmug-ticfyn- @rovmug-ticfyn~sigryn-habrex- Raymond E. Pasco