{"id":13484798,"url":"https://github.com/rhysd/world-map-gen","last_synced_at":"2025-04-14T06:12:36.345Z","repository":{"id":57399392,"uuid":"165104249","full_name":"rhysd/world-map-gen","owner":"rhysd","description":"🗺️Random world map generator CLI and library for Rust and WebAssembly","archived":false,"fork":false,"pushed_at":"2019-08-21T13:42:08.000Z","size":752,"stargazers_count":87,"open_issues_count":0,"forks_count":6,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-14T06:12:31.379Z","etag":null,"topics":["game","generator","npm","rust","wasm","world-map"],"latest_commit_sha":null,"homepage":"https://rhysd.github.io/world-map-gen/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rhysd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-01-10T17:40:57.000Z","updated_at":"2025-02-06T14:33:02.000Z","dependencies_parsed_at":"2022-09-04T00:01:54.028Z","dependency_job_id":null,"html_url":"https://github.com/rhysd/world-map-gen","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Fworld-map-gen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Fworld-map-gen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Fworld-map-gen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Fworld-map-gen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rhysd","download_url":"https://codeload.github.com/rhysd/world-map-gen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248830398,"owners_count":21168272,"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":["game","generator","npm","rust","wasm","world-map"],"created_at":"2024-07-31T17:01:33.945Z","updated_at":"2025-04-14T06:12:36.322Z","avatar_url":"https://github.com/rhysd.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"Random World Map Generator\n==========================\n[![crates.io][crate-badge]][crate]\n[![npm version][npm-badge]][npm]\n[![documentation][doc-badge]][doc]\n[![CI on Linux and macOS][travis-ci-badge]][travis-ci]\n[![CI on Windows][appveyor-badge]][appveyor]\n\n`world-map-gen` is a CLI tool and library for Rust and WebAssembly.\nIt provides functionality to generate a random world map for games like a retro tactical simulation game.\nA generated map consists of cells. Each cell has its altitude and kind (sea, town, plain, forest, mountain, ...).\n\nTry it on browser by visiting [project page][proj] or on your terminal by installing [CLI app][crate].\n\nScreenshot:\n\n### Example of generated 120x120 map in 3D\n\n![screenshot of 3D map](https://github.com/rhysd/ss/blob/master/world-map-gen/3d.png?raw=true)\n\n### Example of generated map in 2D\n\n![screenshot of 2D map](https://github.com/rhysd/ss/blob/master/world-map-gen/2d.png?raw=true)\n\n### Example of generated map in terminal (iTerm2)\n\n![screenshot of map in terminal](https://github.com/rhysd/ss/blob/master/world-map-gen/term.png?raw=true)\n\nThis project is my personal practice to create a Rust library which works fine as both normal Rust\nlibrary and WebAssembly library, which is a bit more practical than\n[awesome Rust+Wasm tutorial](https://rustwasm.github.io/book/game-of-life/introduction.html).\n\nI leaned the algorithm to generate world maps from [this small book](https://www.amazon.com/dp/B07MXZTTCW)\nand implemented it (with small improvements).\n\n\n\n## Installation\n\n### Try random map generation at project page\n\n[gh-page of this project][proj] is a demo page for showing how this package works. The demo site\nis constructed with TypeScript, WebAssembly (thanks to [wasm-pack][], [wasm-bindgen][]) and webpack.\nThe source code of the page is in [`www/`](./www) directory.\n\n### As Rust library\n\nThis library is shipped as [a crate][crate]. It can be installed with [cargo][]\npackage manager.\n\nPlease add a dependency in your project's `Cargo.toml` and run `cargo build`.\n\n```toml\nworld-map-gen = \"0.1\"\n```\n\nRust compiler supporting Rust 2018 edition is necessary.\n\n### As WebAssembly library\n\nThis library built as WebAssembly is shipped as [npm package][npm].\n\n```\nnpm install --save world-map-gen\n```\n\nThe package contains optimized `.wasm` binary, `.js` JS file to glue between Wasm and JS, and `.d.ts`\ntype definition file to use this package with TypeScript.\n\n### As command line tool\n\nUsing [cargo][], please build CLI tool from source.\n\n```\ncargo install world-map-gen\n```\n\nIt builds `~/.cargo/bin/world-map-gen`.\n\n\n\n## Usage\n\n### Rust library\n\nRust library provides some modules to handle a world map as one board filled up with cells.\n\n- `land`: `land::Land` struct represents each cell in a board\n- `board`: `board::Board` struct represents one world map. The struct is JSON serializable with\n  `serde_json`\n- `draw`: Helper to draw a board to terminal or as JSON\n- `gen`: A random world map generator to build `board::Board` struct. It provides algorithms for\n  3 kinds of resolutions; low, middle, high\n- `error`: Error type which may be returned from a map generator\n\nPlease read [the documentation][doc] for more details. And [CLI code](./src/main.rs) is a good\nlive example to know the usage.\n\n```rust\nextern world_map_gen;\n\nuse world_map_gen::RandomBoardGen;\n\n// Create generator instance with default random number generator\nlet mut generator = RandomBoardGen::default();\n\n// Generate 40x40 random world map. Map resolution (low, middle, high) is automatically\n// determined by its width and height here.\n//   - Low: width and height are less than 15\n//   - Middle: width and height are less than 120\n//   - High: Otherwise\nlet board = generator.gen_auto(40, 40);\n\n// Iterate each cells per row\nfor (i, row) in board.rows().enumerate() {\n    println!(\"Row: {}\", i);\n    for cell in row {\n        // cell is a world_map_gen::land::Land instance\n\n        // Lands are categorized with kind (e.g. Sea, Plain, Forest, Mountain, ...)\n        println!(\"Kind: {:?}\", cell.kind);\n\n        // Each cell as its altitude. For example, sea's altitude is lower and mountain's is\n        // higher\n        println!(\"Altitude: {}\", cell.altitude);\n    }\n}\n```\n\n### WebAssembly library\n\n[www/](./www) directory is a good live example to show how to use this package in TypeScript and\nWebAssembly. It is hosted at [gh-pages][proj].\n\n[The npm package][npm] contains `world_map_gen.wasm` and `world_map_gen.js`. The `world_map_gen.js`\nis an entry point. Bundler which support WebAssembly like [webpack](https://github.com/webpack/webpack)\nhandles the `.wasm` file properly when your code imports `world-map-gen` package.\n\n```javascript\nimport { Generator, LandKind } from 'world-map-gen';\n\n// Generate a new random map generator\nconst gen = Generator.new();\n\n// Generate random 200x200 map\nconst board = gen.gen(200, 200);\n\nfor (let x = 0; x \u003c board.width(); x++) {\n    for (let y = 0; y \u003c board.height(); y++) {\n        // Get cell of specific position\n        const cell = board.at(x, y);\n\n        // Get land kind like Sea, Forest, Mountain, ...\n        console.log('Kind:', cell.kind, 'at', x, y);\n\n        // Check the cell is town\n        console.log('  town?:', cell.kind === LandKind.Town);\n\n        // Get altitude of the cell\n        console.log('  Altitude:', cell.altitude);\n\n        // Get color code of the cell as #rrggbb format\n        console.log('  Color:', cell.color_code());\n\n        // Get land legend\n        console.log(' Legend:', cell.legend());\n    }\n}\n\n// Get JSON representation of board\nconsole.log(JSON.parse(board.as_json()))\n```\n\nLet's say this code is put as a file `index.js`.\n\nAs the entry point of your application, please ensure to use [dynamic import](https://github.com/tc39/proposal-dynamic-import/#import).\nIt is necessary because all `.wasm` code must be imported asynchronously.\n\n```javascript\nimport(\"./index\")\n  .catch(e =\u003e console.error(\"Error importing `index.js`:\", e));\n```\n\n`world-map-gen` package also contains `world_map_gen.d.ts` for working with TypeScript. You don't\nneed to write type definitions of APIs. TypeScript compiler automatically detects the `.d.ts` file.\n\nPlease ensure to use `esNext` for module resolution of TypeScript compiler. It translates\nTypeScript's import statements into ES Modules and webpack will handle them later.\n\n```\n{\n  \"compilerOptions\": {\n    \"module\": \"esNext\",\n    // ...\n  },\n  // ...\n}\n```\n\n### CLI tool\n\nPlease read `world-map-gen --help` output to know the interface.\n\nEach cell is represented with ██. And ANSI 256 colors are used for cell colors. Some terminal\nmay not work properly. I'm testing this CLI tool on iTerm2.\n\nBy default, it gets terminal's width and height and uses entire terminal screen to show map.\nYou may need to make font size smaller temporarily to show larger maps. Map's resolution is\nautomatically determined from width and height by default. And you can specify them by command line\noptions. And `--json` outputs a randomly generated map as JSON.\n\n```\nUSAGE:\n    world-map-gen [FLAGS] [OPTIONS]\n\nFLAGS:\n    -a, --altitude    Show altitude instead of squre as cell mainly for debug\n        --help        Prints help information\n    -j, --json        Output JSON-serialized result to stdout\n    -V, --version     Prints version information\n\nOPTIONS:\n    -h, --height \u003cINTEGER\u003e       Board height in number of cells\n    -r, --resolution \u003cSTRING\u003e    Resolution of world map [possible values: low, middle, high]\n    -s, --seed \u003cINTEGER\u003e         Seed for random number generator\n    -w, --width \u003cINTEGER\u003e        Board width in number of cells\n```\n\n\n\n## Development\n\n[Makefile](./Makefile) provides useful scripts to develop this repository.\n\nFor debugging Wasm package from browser, please build this package with [wasm-pack][] and\n`--features wasm_debug`.\n\n\n\n## License\n\nDistributed under [the MIT License](LICENSE.txt).\n\n\n[proj]: https://rhysd.github.io/world-map-gen\n[crate]: https://crates.io/crates/world-map-gen\n[crate-badge]: https://img.shields.io/crates/v/world-map-gen.svg\n[npm-badge]: https://badge.fury.io/js/world-map-gen.svg\n[npm]: https://www.npmjs.com/package/world-map-gen\n[doc-badge]: https://docs.rs/world-map-gen/badge.svg\n[doc]: https://docs.rs/world-map-gen\n[wasm-pack]: https://github.com/rustwasm/wasm-pack\n[wasm-bindgen]: https://github.com/rustwasm/wasm-bindgen\n[cargo]: https://github.com/rust-lang/cargo\n[appveyor-badge]: https://ci.appveyor.com/api/projects/status/aitu2ritu4rcsykb?svg=true\n[appveyor]: https://ci.appveyor.com/project/rhysd/world-map-gen/branch/master\n[travis-ci-badge]: https://travis-ci.org/rhysd/world-map-gen.svg?branch=master\n[travis-ci]: https://travis-ci.org/rhysd/world-map-gen\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhysd%2Fworld-map-gen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhysd%2Fworld-map-gen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhysd%2Fworld-map-gen/lists"}