Skip to content

docs: honest homepage gallery, doc-drift note, CONTRIBUTING.md #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
burinc merged 1 commit into from
Sep 7, 2026
Merged

docs: honest homepage gallery, doc-drift note, CONTRIBUTING.md #6

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 60 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
# Contributing

This project is built by the community and the team behind it, and we would
love your suggestions for improvement. If something is missing, unclear, or
just plain wrong, please let us know: open an issue for a question or a
gap, and a pull request for anything you have already worked out.

Two things worth reading first, so a report doesn't retread known ground:

- `README.md` and `tools/android/RUNBOOK.md` both say, more than once, that
this port has not yet been run on Android hardware. A report that only
reproduces "the docs describe something no real device has confirmed" is
already known.
- Jolt itself, and the libraries this project sits on (raylib-jlt,
jolt-lang/nrepl, the pinned raylib revision), are still evolving. Check
the version pins in `deps.edn` against what you actually have installed
before filing a mismatch as a bug here.

## Etiquette

Adapted from the Clojure community's own
[etiquette guide](https://clojure.org/community/etiquette), since it says
what we would want to say ourselves and says it well.

Issues, pull requests and discussion here are for people who make things.
Most messages should have one of these forms:

- I made something. Here is my contribution.
- I am trying to use this and having trouble, please help.
- I can help you with that.
- I am trying to build something on top of this and having trouble, please
help.
- I can help you build something.

They are not the place for opinion pieces or diatribes, and not the place
for advocacy about what "ought" to be built. If you think something ought
to exist, the fastest way to find out is to build it and send a pull
request. Otherwise, respect that other people get to choose what they do
with their time.

Disagreements about how something has been, or will be, done should take
the form of technical arguments. A technical argument that gets, and
gives, respect:

- Keeps it short.
- Sticks to the facts.
- Uses logic.
- Leaves people out of it.
- Avoids rhetorical devices: superfluous or opinion-laden adjectives,
claims to speak for the community or that everyone agrees with you,
threats of what will happen unless things go your way, any flavour of
"the sky is falling."

If you are not the one doing the work, restrict your input to short
technical arguments supporting your position. If someone has already made
your point, a "+1" is enough, and keeping posts short is worth doing on
its own.

Ignoring these guidelines costs the time of the people who make things,
which is worth caring about if you intend to be one of them.
13 changes: 13 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,12 @@ RUNBOOK says the same thing at the top, for the same reason: what follows
below is read off the pinned raylib source and the code in this tree, not
measured on a phone.

These docs are also a moving target. Jolt and the libraries this project
sits on (raylib-jlt, jolt-lang/nrepl, the pinned raylib revision) are still
evolving, so a detail here can go stale between one release and the next.
Check the version pins in `deps.edn` against what you actually have
installed before assuming a mismatch is a bug in this repository.

What exists today: a gallery of seventeen scenes in four categories, each one
a pure `.cljc` simulation, under an Android owner loop of about thirty lines.
The scene contract is tested on the build host (`jolt test`, no device
Expand Down Expand Up @@ -357,6 +363,13 @@ every frame — `raylib.flappy` and `raylib.touch` — were always fine.
both offsets at 0 — so the screen is the native window in physical pixels
and nothing scales. Ask for a size instead and raylib letterboxes into it.

## Contributing

This is built by the community and the team behind it, and a suggestion for
improvement or a "this is missing" is exactly the kind of thing to open an
issue about. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the etiquette we
ask discussion and pull requests to follow, adapted from Clojure's own.

## Licence

[zlib](LICENSE), matching
Expand Down
12 changes: 6 additions & 6 deletions docs/check-site.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,12 +41,12 @@ for page in performance-on-a-phone porting-an-example; do
test -f "$out/guide/$page.html" || { echo "missing guide page: $page"; exit 1; }
done

# The homepage links every scene, and the two most recent are the ones most
# likely to be forgotten when the grid is edited.
for img in lorenz.gif tesseract.gif; do
grep -q "$img" "$out/index.html" || { echo "homepage does not show $img"; exit 1; }
test -f "$out/images/$img" || { echo "missing image: $img"; exit 1; }
done
# The homepage used to embed a scene grid, and this checked the two most
# recent scenes stayed in it when the grid was edited. The grid is gone for
# now: every one of those captures was a real raylib-ios screen recording,
# not an Android one, and the homepage says so instead of showing them. Bring
# this check back, naming whichever scenes are newest at the time, once the
# grid comes back with real Android captures.

# The base path has to reach the emitted HTML, not just site.edn. Getting this
# wrong is the failure mode the engine's own README calls out: the pages render
Expand Down
114 changes: 18 additions & 96 deletions docs/templates/home.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,15 @@ <h1>raylib on an Android phone, from Clojure</h1>
dependencies.
</p>
<p class="tagline">
<em>The captures below come off the sibling build this was ported from;
the scenes are the same files. This host has not yet met an Android
device, and no frame time here was measured on one.</em>
<strong>Work in progress: this has not yet been run on Android
hardware.</strong> What follows is read off the pinned raylib source
and the code in this tree, not measured on a phone.
</p>
<p class="tagline">
<em>These docs are also a moving target: Jolt and the libraries this
project sits on (raylib-jlt, jolt-lang/nrepl, the pinned raylib
revision) are still evolving, so a detail here can go stale between
one release and the next.</em>
</p>
<div class="hero-actions">
<a class="btn btn-primary" href="{{site-base}}/guide/porting-an-example.html">Read the guide</a>
Expand Down Expand Up @@ -127,101 +133,17 @@ <h2>The gallery</h2>
itself. The other fourteen are ports from
<a href="https://github.com/jlt-commons/raylib-jlt">raylib-jlt</a>.
</p>
<div class="demo-grid">
<a class="demo" href="{{site-base}}/guide/porting-an-example.html">
<img src="{{site-base}}/images/spirograph.gif" alt="A hypotrochoid drawing itself in rainbow lines" loading="lazy" width="480">
<figcaption>spirograph &middot; 55 fps</figcaption>
</a>
<a class="demo" href="{{site-base}}/guide/performance-on-a-phone.html">
<img src="{{site-base}}/images/kaleidoscope.gif" alt="A stroke mirrored into six-fold symmetry" loading="lazy" width="480">
<figcaption>kaleidoscope &middot; 58 fps</figcaption>
</a>
<a class="demo" href="{{site-base}}/guide/porting-an-example.html">
<img src="{{site-base}}/images/fireworks.gif" alt="Rockets bursting into falling sparks" loading="lazy" width="480">
<figcaption>fireworks &middot; 58 fps</figcaption>
</a>
<a class="demo" href="{{site-base}}/guide/porting-an-example.html">
<img src="{{site-base}}/images/boids.gif" alt="Forty-five boids flocking" loading="lazy" width="480">
<figcaption>boids &middot; 52 fps</figcaption>
</a>
<a class="demo" href="{{site-base}}/images/flappy-bird.png">
<img src="{{site-base}}/images/flappy-bird.gif" alt="Flappy Bird, flapped by a loop inside the app" loading="lazy" width="480">
<figcaption>flappy-bird &middot; unchanged from Android</figcaption>
</a>
<a class="demo" href="{{site-base}}/guide/porting-an-example.html">
<img src="{{site-base}}/images/pendulum.gif" alt="A chaotic double pendulum tracing its path" loading="lazy" width="480">
<figcaption>double-pendulum &middot; 59 fps</figcaption>
</a>
<a class="demo" href="{{site-base}}/guide/porting-an-example.html">
<img src="{{site-base}}/images/epicycles.gif" alt="Fourier epicycles drawing a square wave" loading="lazy" width="480">
<figcaption>fourier-epicycles &middot; 59 fps</figcaption>
</a>
<a class="demo" href="{{site-base}}/guide/performance-on-a-phone.html">
<img src="{{site-base}}/images/tree.gif" alt="A binary fractal tree swaying" loading="lazy" width="480">
<figcaption>fractal-tree &middot; 59 fps</figcaption>
</a>
<a class="demo" href="{{site-base}}/guide/performance-on-a-phone.html">
<img src="{{site-base}}/images/stars.gif" alt="A starfield flying toward the viewer" loading="lazy" width="480">
<figcaption>starfield &middot; 58 fps</figcaption>
</a>
<a class="demo" href="{{site-base}}/images/hilbert.png">
<img src="{{site-base}}/images/thumbs/hilbert.png" alt="A Hilbert space-filling curve" loading="lazy" width="480">
<figcaption>hilbert-curve &middot; 1023 lines at 60 fps</figcaption>
</a>
<a class="demo" href="{{site-base}}/guide/porting-an-example.html">
<img src="{{site-base}}/images/lsystem.gif" alt="An L-system plant growing segment by segment" loading="lazy" width="480">
<figcaption>l-system &middot; 1488 segments at 59 fps</figcaption>
</a>
<a class="demo" href="{{site-base}}/guide/performance-on-a-phone.html">
<img src="{{site-base}}/images/flowfield.gif" alt="Particles following a drifting flow field" loading="lazy" width="480">
<figcaption>flow-field &middot; 54 fps, tuned down from 32</figcaption>
</a>
<a class="demo" href="{{site-base}}/guide/performance-on-a-phone.html">
<img src="{{site-base}}/images/lorenz.gif" alt="The Lorenz attractor, camera orbiting a 450-point trail" loading="lazy" width="480">
<figcaption>lorenz &middot; 58 fps, and where the budget rule broke</figcaption>
</a>
<a class="demo" href="{{site-base}}/guide/porting-an-example.html">
<img src="{{site-base}}/images/tesseract.gif" alt="A rotating 4D hypercube projected to the screen" loading="lazy" width="480">
<figcaption>tesseract &middot; 32 edges, the cheapest scene here</figcaption>
</a>
<a class="demo" href="{{site-base}}/images/penrose.png">
<img src="{{site-base}}/images/thumbs/penrose.png" alt="A Penrose P3 tiling by deflation" loading="lazy" width="480">
<figcaption>penrose &middot; 57 fps</figcaption>
</a>
<a class="demo" href="{{site-base}}/images/following-eyes.png">
<img src="{{site-base}}/images/thumbs/following-eyes.png" alt="Two eyes whose pupils follow a finger" loading="lazy" width="480">
<figcaption>following-eyes &middot; unchanged from Android</figcaption>
</a>
<a class="demo" href="{{site-base}}/images/touch-trail.png">
<img src="{{site-base}}/images/thumbs/touch-trail.png" alt="A fading trail following the primary pointer" loading="lazy" width="480">
<figcaption>touch-trail &middot; unchanged from Android</figcaption>
</a>
<a class="demo" href="{{site-base}}/images/gallery.png">
<img src="{{site-base}}/images/thumbs/gallery.png" alt="The category screen" loading="lazy" width="480">
<figcaption>the gallery &middot; two levels</figcaption>
</a>
</div>
<p>
generative 6 &middot; fractals 3 &middot; toys 5 &middot; games 1 &middot; three of them byte-identical to the
Android originals. <em>Every capture and every frame rate on this page
came off the sibling build this was ported from, not off an Android
device — the scenes are the same files, so they are what to compare
against rather than what to quote. Nobody touched the device for any of
them: Flappy Bird is flapped by a loop running inside the app, started
from the nREPL.</em>
There are no screenshots here yet, for the same reason there are none
in the README: nothing has run on Android to photograph honestly. Every
capture that stood here before was a real screen recording, phone
status bar and all, but of <a
href="https://github.com/jlt-commons/raylib-ios">raylib-ios</a>, the
sibling project this tree was ported from, not of this build. That
project's own site has the captures and frame rates for what the
scenes draw, and this section gets real Android ones once this build
has actually met a phone.
</p>

<table>
<thead><tr><th>Scene</th><th>Per frame</th><th>fps</th></tr></thead>
<tbody>
<tr><td>Kaleidoscope</td><td>708 lines</td><td>58</td></tr>
<tr><td>Fireworks</td><td>~120 circles</td><td>58</td></tr>
<tr><td>Penrose</td><td>340 triangles, ~2400 FFI calls</td><td>57</td></tr>
<tr><td>Spirograph</td><td>~1000 lines</td><td>55</td></tr>
<tr><td>Boids</td><td>2025 distance tests</td><td>52</td></tr>
<tr><td>Flappy Bird, Following Eyes, Touch Trail</td><td>byte-identical from Android</td><td>58</td></tr>
</tbody>
</table>
</div>
</section>

Expand Down