{"id":16190056,"url":"https://github.com/brson/ferris-fencing","last_synced_at":"2025-10-04T16:59:03.749Z","repository":{"id":35786819,"uuid":"215942912","full_name":"brson/ferris-fencing","owner":"brson","description":null,"archived":false,"fork":false,"pushed_at":"2022-06-17T01:21:52.000Z","size":450,"stargazers_count":42,"open_issues_count":8,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-12-24T11:17:39.001Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-18T04:44:40.000Z","updated_at":"2022-02-23T15:21:46.000Z","dependencies_parsed_at":"2022-09-04T02:02:30.876Z","dependency_job_id":null,"html_url":"https://github.com/brson/ferris-fencing","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brson%2Fferris-fencing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brson%2Fferris-fencing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brson%2Fferris-fencing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brson%2Fferris-fencing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brson","download_url":"https://codeload.github.com/brson/ferris-fencing/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":231501580,"owners_count":18386285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T07:38:25.064Z","updated_at":"2025-10-04T16:58:58.682Z","avatar_url":"https://github.com/brson.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ferris Fencing\n\n\u003e An eternal duel between programmable crabs with swords.\n\n[Ferris Fencing][fforg] is a live tournament in which player-programmed bots combat each\nother on a [RISC-V] virtual machine.\n\nIt is a showcase of [CKB-VM], a simple implementation of the RISC-V instruction\nset, written in the [Rust] programing language.\n\n[www.ferrisfencing.org][fforg]\n\n[fforg]: http://www.ferrisfencing.org\n[RISC-V]: https://www.riscv.org\n[CKB-VM]: https://github.com/nervosnetwork/ckb-vm\n[Rust]: https://www.rust-lang.org\n\n\n## Status\n\nFerris Fencing is in early development. It does not yet run in the cloud, and\nthe final rules are not yet determined.\n\nFor now, it is possible to write bots in Rust, compile them to RISC-V, and run\nthem locally with the Ferris Fencing runtime.\n\nSoon, players will be able to upload their bots to the Ferris Fencing server\nto challenge others' bots.\n\n\n## The Rules\n\nSee [www.ferrisfencing.org][fforg] for the game rules.\n\n\n## Building and running\n\nFor simplicity, we suggest building off the code in the brson/ferris-fencing\nworkspace, which contains the runtime, example bots, command line tools, and the\nweb server.\n\nThis project uses a nightly toolchain, because bots are running on (virtual)\nbare-metal RISC-V, and that requires some nightly features. The exact toolchain\nis listed in the `rust-toolchain` file in the repo, and will be used\nautomatically.\n\nFor building bots this project requires the `riscv32-imac-unknown-none-elf`\ncompiler target.\n\nThe following commands will set you up:\n\n```\ngit clone https://github.com/brson/ferris-fencing.git\ncd ferris-fencing\nrustup target add riscv32imac-unknown-none-elf\n```\n\nThe repository is a `cargo` workspace that contains the following projects, in\nthe `src` directory, each of which can be build or run with the `cargo` `-p`\nflag:\n\n- `ckb_vm_glue` - A basic bot runtime library containing the boilerplate\n  necessary to run `main`. Think of it as `std` for the Ferris Fencing platform.\n- `ckb_vm_syscall` - Assembly-language trampolines for calling RISC-V syscalls.\n- `example_bot` - A working Ferris Fencing bot.\n- `ff_local` - The CLI for running a local match between two bots.\n- `ff_rt` - The Ferris Fencing platform runtime. The game logic.\n- `ff_web` - The Ferris Fencing web API.\n- `ff_web_common` - Support library for the website.\n- `ff_web_json` - Runs a match and emits json.\n\nIt also contains two `demo_*` projects. These were used in the [Rust.Tokyo 2019]\ntalk for which Ferris Fencing was made. On their own they are relatively\nuninteresting.\n\n[Rust.Tokyo 2019]: https://rust.tokyo\n\nNote that the projects in this workspace are a mixture of standard desktop\nprojects and RISC-V-specific projects. Because of this, at the moment, running\n`cargo` with the `--all` flag will fail. By default `cargo build` and\n`cargo run` will build `ff_local`.\n\n\n### Building the example bot\n\n```\ncargo build -p example_bot --target=riscv32imac-unknown-none-elf\n```\n\nThis will put a binary in\n\n\u003e target/riscv32imac-unknown-none-elf/debug/ff-example-bot\n\n\n### Running a match\n\n```\nexport EXAMPLE_BOT=target/riscv32imac-unknown-none-elf/debug/ff-example-bot\ncargo run -p ff_local -- $EXAMPLE_BOT $EXAMPLE_BOT\n```\n\n(The `export` here is just to make the tabove more readable. You can just type\nthe paths out).\n\nAdding `RUST_LOG=debug` will log some useful info about what is happening\nin the VM and the Ferris Fencing runtime.\n\n\n### Building your own bot\n\nEither edit `example_bot` in place or copy it elsewhere as a template to work\noff of.\n\n\n### The RISC-V gcc toolchain\n\nHaving a RISC-V gcc toolchain may be useful for debugging, assembly,\ndissassamebly, and writing C. The following commands will build and install them\nto `$HOME/riscv-gcc`.\n\n```\ngit clone --recursive https://github.com/riscv/riscv-gnu-toolchain\ncd riscv-gnu-toolchain\nmkdir build \u0026\u0026 cd build\n../configure --prefix=$HOME/riscv-gcc --with-arch=rv32imac --with-abi=ilp32\nmake install\n```\n\nFor example, to decompile the example bot:\n\n```\n ~/riscv-gcc/bin/riscv32-unknown-elf-objdump -d target/riscv32imac-unknown-none-elf/debug/ff-example-bot\n```\n\n\n## Roadmap\n\nHere's a vague description of the MVP:\n\n- Players can upload bots via the `ff_upload` command.\n- Player bots consist of an `elf` exe, a single-grapheme name (emoji\n  encouraged), and a 128-bit random identifier.\n- The website is static but contains a live.html frame that contains all the\n  dynamic logic. This frame can be embedded elsewhere as needed.\n- On load, live.html requests a random match; the server generates\n  it and responds; live.html interprets the results by moving\n  Ferris, energy bars, move indicators, and the scoreboard.\n- After a match is complete, live.html requests another.\n- The number of bots is capped to prevent abuse, and are \"garbage collected\" in\n  FIFO order.\n- The game rules are improved to be interesting.\n\nThere is extensive potential beyond the MVP, but this first.\n\n\n## Contributions\n\nContributions for bug fixes, and toward the MVP, welcome.\n\n\n## License\n\nApache-2.0/MIT/BSL-1.0/CC-0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrson%2Fferris-fencing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrson%2Fferris-fencing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrson%2Fferris-fencing/lists"}