{"id":13468908,"url":"https://github.com/Gjum/CivMap","last_synced_at":"2025-03-26T05:31:24.014Z","repository":{"id":12132991,"uuid":"69041531","full_name":"Gjum/CivMap","owner":"Gjum","description":"Interactive, editable personal web map for Civ-style Minecraft servers","archived":false,"fork":false,"pushed_at":"2023-08-10T22:48:52.000Z","size":554,"stargazers_count":22,"open_issues_count":14,"forks_count":11,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-18T10:45:51.176Z","etag":null,"topics":["leaflet","minecraft","react","redux"],"latest_commit_sha":null,"homepage":"https://ccmap.github.io/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Gjum.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-23T16:20:06.000Z","updated_at":"2024-08-05T07:07:43.000Z","dependencies_parsed_at":"2024-01-18T20:05:29.706Z","dependency_job_id":null,"html_url":"https://github.com/Gjum/CivMap","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gjum%2FCivMap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gjum%2FCivMap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gjum%2FCivMap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Gjum%2FCivMap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Gjum","download_url":"https://codeload.github.com/Gjum/CivMap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245597341,"owners_count":20641866,"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":["leaflet","minecraft","react","redux"],"created_at":"2024-07-31T15:01:21.693Z","updated_at":"2025-03-26T05:31:23.375Z","avatar_url":"https://github.com/Gjum.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# CivMap\n\nInteractive, editable personal web map for [Civ-style](https://www.reddit.com/r/CivClassics/) Minecraft servers\n\nUsed for [CivClassic](https://ccmap.github.io/), [DevotedMC 3.0](https://dev3map.github.io/), [CivEx](https://civexmap.github.io/).\n\nThe custom map tiles (height, biome, landmasses, night) are created with [a different project](https://github.com/Gjum/voxelmap-cache).\n\n## API\n\n### Collection Format\n\n- `info`: `{ \"version\": \"3.0.0-beta3\", \"last_update\": 1553379758 }`\n  - `version`: must be set to current version (`\"3.0.0-beta3\"`) to allow converting to future versions\n  - `last_update`: unix timestamp (seconds), optional\n- `name`: displayed in the layer selector menu\n- `features`: array of [feature objects](#feature-format), optional\n- `presentations`: array of [presentation objects](#presentation-format), optional\n- `enabled_presentation`: presentation name that will be shown when collection is loaded, if unset defaults to first presentation\n\n### Feature Format\n\nA typical feature looks like this:\n\n```js\n{\n  \"id\": \"e767a0bc-9df0-4ec1-87b7-f5cb528bb38b\", // must be globally unique\n  \"name\": \"Mount Augusta\", // displayed in sidebar, typically styles use this as label\n  \"x\": -6700, \"z\": 3000, // or \"line\", \"polygon\", etc. - see below\n  \"image\": \"https://example.com/MtA-Render.png\", // shows up in the sidebar\n  \"web\": \"/r/MtAugusta\" // arbitrary properties are ok, \"/r/\" etc. get rendered as clickable link\n}\n```\n\n`id` must be globally unique. CivMap uses UUIDs internally but this can be any text (e.g. namespaced: `\"com.github.gjum.civclassic.railmap.stations.westminster\"`).\nThey are needed for updating old features with new info and referring from one feature to another.\n\n`polygon, line, x, z, radius, map_image` represent the feature's geometry on the map.\nAny feature can have any combination of these, the chosen geometry is currently prioritized `image \u003e polygon \u003e line \u003e circle \u003e marker`. In a future version, the geometry with the biggest surface at the current zoom level will be displayed (marker when zoomed out so the feature only covers a few pixels, polygon/line/circle/image when zoomed in).\n\n- `{ \"map_image\": { \"bounds\": [[w,n],[e,s]], \"url\": \"https://example.com/overlay.png\" } }` where `w/n/e/s` are west/north/east/south. Accepts PNG, JPG, SVG (but avoid SVGs covering large areas, currently they lag some browsers when zoomed in)\n- `{ \"polygon\": [ [ [x1,z1], [x2,z2], … ], [optional: holes or more polygon parts], … ] }` The polygon will be closed automatically, you do not need to duplicate the first/last point.\n- `{ \"line\": [ [ [x1,z1], [x2,z2], … ], [optional: more line parts], … ] }`\n- polygons/lines also allow a string like `\"(((x1,z1!x2,z2!…)),…)\"` instead (more compact, used in export URLs)\n- circle: `{ \"x\": 123, \"z\": -321, \"radius\": 456 }`\n- point: `{ \"x\": 123, \"z\": -321 }`\n\nAll coordinates are centered on the center of a block, except image bounds which align with a block's NW corner.\n\n`name` and `image` are also special:\n\n- `name`: shown in sidebar selecion menues, distinguishes between all features, ex: `Westminster Rail Station`\n- `image`: direct URL, shown in Feature Details\n\n### Presentation Format\n\nThe \"presentation\" lets you control the style attributes of the features.\n\n- `style_base` is the same for all features in the collection\n- one of the `zoom_styles` is applied to all features according to the current zoom level (see example below)\n- `style_highlight` is only applied to highlighted features (selection, search results, ...)\n\nThe overriding order is: `combinedStyle = { ...baseStyle, ...zoomStyle, ...highlightStyle }`\nThe result will be passed through this function and then applied to the leaflet element ([code](https://github.com/Gjum/CivMap/blob/master/app/js/utils/presentation.js#L102)).\n\n#### Style Format\n\n- `label` (default `$name`)\n- `opacity` (fill and stroke; 0 means the feature is invisible)\n- `fill_opacity`\n- `color` (fill and stroke)\n- `hue` (`[0..360]`; overrides color if set)\n- `stroke_color`\n- `stroke_width`\n- `dash_array`\n- `icon_size`\n- `icon` (URL; a circle by default)\n\nMore details on marker icon styles in the [code](https://github.com/Gjum/CivMap/blob/master/app/js/components/leaflet/EditableMarker.jsx#L10)\n\n#### Presentations Example\n\n```js\n{ // ... other collection properties omitted ...\n  \"presentations\": [\n    // there can be none (=default styles), one, or several presentations\n    // if there's several, the sidebar lets the user select which one to use for this collection\n    {\n      \"name\": \"Rails and Stops\", // when there's more than one presentation, this name will show up in the sidebar\n      \"style_base\": {\n        \"color\": \"#ffffff\", // primitives are applied to all features\n        // $-prefixed feature keys resolve to the value of that feature property\n        // | separates a fallback value: style = feature[key] || fallback\n        // this will be fixed to use undefined/NaN check, to allow 0, '', and false as values\n        \"label\": \"$nice_name|(unnamed)\",\n        // objects specify how to compute the style from the feature props\n        \"stroke_color\": {\n          // category selectors are like a switch-case statement\n          // for each feature, its \"stroke_color\" style depends on the feature's \"elevation\" property\n          \"feature_key\": \"elevation\",\n          \"categories\": {\n            \"underground\": \"#00ff00\",\n            \"surface\": \"#00ffff\",\n            // the value can also be another nested selector\n            \"elevated\": {\n              \"feature_key\": \"elevation_type\",\n              \"categories\": {\n                \"skylimit\": \"#123123\",\n                \"viaduct\": \"#345345\"\n              },\n              \"default\": \"#234234\"\n            }\n          },\n          \"default\": \"#808080\"\n        },\n        \"stroke_width\": {\n          // range selectors linearly map the value of a feature property to a style value, interpolating/extrapolating appropriately\n          // implementation: https://github.com/Gjum/CivMap/blob/master/app/js/utils/presentation.js#L50\n          \"feature_key\": \"num_tracks\",\n          \"range\": {\n            \"min_in\": 1, \"max_in\": 5, // in feature units\n            \"min_out\": 2, \"max_out\": 10 // in style units (here: px)\n          }\n        }\n      },\n      \"zoom_styles\": {\n        // searched in ascending order for the largest key that is smaller than or equal to the current zoom\n        \"-6\": { // zoomed out all the way\n          // each zoom entry is structured exactly the same as style_base\n          \"opacity\": {\n            // example: only features with \"importance\":\"major\" are visible when zoomed out\n            \"feature_key\": \"importance\",\n            \"categories\": {\n              \"major\": 1\n            },\n            \"default\": 0\n          }\n        },\n        \"0\": { // zoomed in at 1 block to 1 pixel\n          \"opacity\": 1 // now all features are visible\n        }\n      },\n      // style_highlight is structured exactly the same as style_base,\n      // but applied to selected/highlighted features in addition to style_base\n      \"style_highlight\": {\n        \"stroke_color\": \"#ff0000\"\n      }\n    }\n  ]\n}\n```\n\n### In-Browser Entry Point\n\nCurrently, the library exposes a [Redux Store](https://redux.js.org/api/store) as `window.CivMap.api`.\n\nSome examples:\n\n```js\nconsole.log(CivMap.api.getState())\n```\n\nreturns a read-only snapshot of the whole application data store:\n\n```js\n{\n  collections: {civmap:collection/user: {…}, /data/settlements.civmap.json: {…}},\n  control: {appMode: \"LAYERS\", searchQuery: null, activeFeatureId: \"e767a0bc-9df0-4ec1-87b7-f5cb528bb38b\", …},\n  mapView: {basemapId: \"simple\", viewport: {x: -123, z: 321, radius: 4321}},\n  // ...\n}\n```\n\nDo not change anything directly, but reading from it is fine.\nTo change something, use [`CivMap.api.dispatch(…)`](https://redux.js.org/api/store#dispatch).\n\nFor example, to add/update a feature:\n\n```js\nCivMap.api.dispatch({\n  type: \"UPDATE_FEATURE_IN_COLLECTION\",\n  collectionId: \"civmap:collection/user\",\n  feature: {\n    id: \"e767a0bc-9df0-4ec1-87b7-f5cb528bb38b\",\n    name: \"My Test Feature\",\n    x: 0, z: 0\n  }\n})\n```\n\nFor now, the action constants and parameters may change any time, and can only be found in the source code ([`app/js/store.js`](https://github.com/Gjum/CivMap/blob/master/app/js/store.js)).\n\n## Installation\n\nAfter cloning the repository, install the dependencies:\n```sh\nnpm install\n```\n\nNow you can run the local development web server:\n```sh\nnpm start\n```\nOpen the map on http://localhost:8080\n\n### Creating a new release\n\nUpdate the version info in `package.json`, create a new tag, and push it to the repository.\n\nClone your `gh-pages` branch to `dist/`:\n```sh\ngit clone --single-branch -b gh-pages git@github.com:YOUR-GITHUB-ACCOUNT/CivMap.git dist/\n```\n\nGenerate `dist/js/bundle.js` and the other assets:\n```sh\nnpm run build\n```\n\nPush `dist/` to `gh-pages`:\n```sh\ncd dist/\ngit commit -a -m \"Release v$version\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGjum%2FCivMap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGjum%2FCivMap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGjum%2FCivMap/lists"}