Difference between revisions of "Mudlet Map Browser"

From Mudlet
Jump to navigation Jump to search
Line 6: Line 6:
 
| By || <!-- handle|alias|name --> Delwing
 
| By || <!-- handle|alias|name --> Delwing
 
|-
 
|-
−
| Download || [https://github.com/Delwing/online-mudlet-map-template Github]
+
| Download || [https://github.com/Delwing/mudlet-map-page Github]
 
|-
 
|-
 
| Dependencies || <!-- any package dependencies|mudlet version requirements --> Mudlet 4.17
 
| Dependencies || <!-- any package dependencies|mudlet version requirements --> Mudlet 4.17
 
|}
 
|}
  
−
= Description =
+
= Publishing a Mudlet map online =
−
<!-- A description about what your script accomplishes. -->
 
  
−
Display Mudlet maps (.dat format) in a web browser for hosting online or locally.
+
This guide uses the [https://github.com/Delwing/mudlet-map-page mudlet-map-page] GitHub Action. You point it at your Mudlet binary map (<code>.dat</code>) and it decodes the map, generates the host page, and deploys it to GitHub Pages — no hand-written HTML and no in-browser <code>.dat</code> decoding.
  
−
e.g: https://delwing.github.io/arkadia-mapa/
+
== Requirements ==
  
−
= Usage =
+
* A GitHub account and a repository to hold your map.
−
Github is a requirement as this script uses Github Actions to produce the resulting static web page.
+
* Your Mudlet map exported as a <code>.dat</code> file. In Mudlet: '''Options → Map → Save map''' (or <code>saveMap()</code> in the command line).
  
−
# Create new repository using this one as template.
+
== Steps ==
−
# Replace map.dat with your own map file
 
−
# Replace logo.svg and favicon.ico
 
−
# In page/i18n/en.json replace %title% and %description%
 
−
# Optionally you can also replace ones in page/index.html
 
−
# You can add npcs to be searchable in page/data/npc.json just as the one that it's there.
 
−
# Push
 
−
# Go to repository Settings -> Pages. In Build and deployment section set Source as Github Actions
 
−
# Visit your page under https://{repositoryOwner}.github.io/{repository}/ so in case if this example it is: https://delwing.github.io/online-mudlet-map-template/
 
  
−
See also: [https://forums.mudlet.org/viewtopic.php?t=22983 Mudlet Forums]
+
=== 1. Add your map to a repository ===
  
−
= Examples =
+
Create a repository (or reuse an existing one) and commit your map file, e.g. <code>maps/map.dat</code>.
  
−
https://delwing.github.io/arkadia-mapa/
+
=== 2. Add the workflow ===
  
−
https://ire-mudlet-mapping.github.io/AchaeaCrowdmap/
+
Create the file <code>.github/workflows/pages.yml</code> with the following content, adjusting <code>map-file</code> and <code>title</code> to match your repo:
 +
 
 +
<syntaxhighlight lang="yaml">
 +
name: Map
 +
 
 +
on:
 +
  push:
 +
    branches: [main]
 +
  workflow_dispatch:
 +
 
 +
permissions:
 +
  contents: read
 +
  pages: write
 +
  id-token: write
 +
 
 +
jobs:
 +
  pages:
 +
    uses: Delwing/mudlet-map-page/.github/workflows/deploy-pages.yml@v1
 +
    with:
 +
      map-file: maps/map.dat
 +
      title: My MUD Map
 +
</syntaxhighlight>
 +
 
 +
'''The <code>permissions</code> block is required.''' GitHub's default token is read-only, and <code>id-token: write</code> (needed for the Pages deploy) is never granted automatically, so the workflow fails at startup without it.
 +
 
 +
=== 3. Enable GitHub Pages ===
 +
 
 +
In your repository go to '''Settings → Pages'''. In the '''Build and deployment''' section set '''Source''' to '''GitHub Actions'''.
 +
 
 +
=== 4. Publish ===
 +
 
 +
Push to your <code>main</code> branch (or run the workflow manually from the '''Actions''' tab via '''Run workflow'''). When the run finishes it publishes the site and prints the URL in the run summary.
 +
 
 +
Your page is served at <code>https://{repositoryOwner}.github.io/{repository}/</code>
 +
 
 +
== Customising the page ==
 +
 
 +
Pass extra options under <code>with:</code>. Common ones:
 +
 
 +
{| class="wikitable"
 +
! Input !! Description
 +
|-
 +
| <code>title</code> || Page title shown in the browser tab and header.
 +
|-
 +
| <code>logo</code> || Logo image — a URL, or a file in your repo (copied into the site).
 +
|-
 +
| <code>npc-url</code> || NPC data file to make NPCs searchable (URL or repo file). Opt-in; without it, room-id search still works.
 +
|-
 +
| <code>favicon</code> || Favicon — a URL, or a repo file copied in as <code>/favicon.ico</code>.
 +
|-
 +
| <code>lang</code> || Document language and default UI language (e.g. <code>pl</code>, <code>en</code>).
 +
|-
 +
| <code>credits-author</code> || Author name shown in the help/credits modal.
 +
|}
 +
 
 +
See the [https://github.com/Delwing/mudlet-map-page#readme project README] for the full list of inputs (version pinning, extra assets, custom translations, etc.).
 +
 
 +
== Examples ==
 +
 
 +
* https://delwing.github.io/arkadia-mapa/
 +
* https://ire-mudlet-mapping.github.io/AchaeaCrowdmap/
 +
 
 +
== See also ==
 +
 
 +
* [https://forums.mudlet.org/viewtopic.php?t=22983 Mudlet Forums thread]
  
 
[[File:Mudlet Map Browser.png|thumb|left|screenshot]]
 
[[File:Mudlet Map Browser.png|thumb|left|screenshot]]

Revision as of 09:11, 21 June 2026

Game non-mud specific
By Delwing
Download Github
Dependencies Mudlet 4.17

Publishing a Mudlet map online

This guide uses the mudlet-map-page GitHub Action. You point it at your Mudlet binary map (.dat) and it decodes the map, generates the host page, and deploys it to GitHub Pages — no hand-written HTML and no in-browser .dat decoding.

Requirements

  • A GitHub account and a repository to hold your map.
  • Your Mudlet map exported as a .dat file. In Mudlet: Options → Map → Save map (or saveMap() in the command line).

Steps

1. Add your map to a repository

Create a repository (or reuse an existing one) and commit your map file, e.g. maps/map.dat.

2. Add the workflow

Create the file .github/workflows/pages.yml with the following content, adjusting map-file and title to match your repo: 

name: Map

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  pages:
    uses: Delwing/mudlet-map-page/.github/workflows/deploy-pages.yml@v1
    with:
      map-file: maps/map.dat
      title: My MUD Map

The permissions block is required. GitHub's default token is read-only, and id-token: write (needed for the Pages deploy) is never granted automatically, so the workflow fails at startup without it.

3. Enable GitHub Pages

In your repository go to Settings → Pages. In the Build and deployment section set Source to GitHub Actions.

4. Publish

Push to your main branch (or run the workflow manually from the Actions tab via Run workflow). When the run finishes it publishes the site and prints the URL in the run summary.

Your page is served at https://{repositoryOwner}.github.io/{repository}/

Customising the page

Pass extra options under with:. Common ones:

Input Description
title Page title shown in the browser tab and header.
logo Logo image — a URL, or a file in your repo (copied into the site).
npc-url NPC data file to make NPCs searchable (URL or repo file). Opt-in; without it, room-id search still works.
favicon Favicon — a URL, or a repo file copied in as /favicon.ico.
lang Document language and default UI language (e.g. pl, en).
credits-author Author name shown in the help/credits modal.

See the project README for the full list of inputs (version pinning, extra assets, custom translations, etc.).

Examples

See also

screenshot
Retrieved from "https://wiki.mudlet.org/index.php?title=Mudlet_Map_Browser&oldid=23105"