Vai al contenuto

Installation and startup

This section details the requirements and procedures to run ChoiceMap on your computer.

Requirements

ChoiceMap has minimal requirements. You need a modern browser (Chrome, Firefox, Safari, Edge in recent versions) and Python to start the local server.

Python is only needed for local development. Once published on a web server, end users don't need Python: they access directly from the browser.

On Windows, Python might not be preinstalled. You can download it from python.org or install it through the Microsoft Store. To check if it's present, open the Command Prompt and type python --version. If a version number (3.x) appears, Python is installed.

On Mac, Python is typically already present. On Linux, it's almost always available by default.

Download the package

The complete package is available as a ZIP file from the project's GitHub page, in the Releases section. The download includes:

  • choicemap.html - the Navigator
  • scenario-editor.html - the editor for creating scenarios
  • theme-editor.html - the editor for customizing themes
  • config.json - configuration file
  • defaults.json - shared default values
  • theme.json - default theme
  • scenario-sample.json - narrative sample scenario
  • scenario-quiz.json - quiz example
  • scenario-workflow.json - workflow example
  • Batch scripts for Windows
  • docs/ folder for downloadable resources

Extract the ZIP to a folder of your choice. The path should not contain special characters or spaces to avoid problems with some systems.

Starting on Windows

The simplest way on Windows is to use the included batch scripts.

Double-click start-navigator.bat to start the server and open the Navigator in the default browser. The script starts a server on port 8000.

Double-click start-scenario-editor.bat to directly open the Scenario Editor.

Double-click start-theme-editor.bat to open the Theme Editor.

If an error appears indicating that Python is not found, you need to install it or add it to the system PATH.

The scripts create a server that stays active as long as the terminal window is open. Closing the window stops the server.

Manual startup

If you prefer not to use the scripts or you're on Mac/Linux, manual startup requires a few commands.

Open a terminal in the project folder. On Windows, you can right-click while holding Shift and select "Open PowerShell window here" or "Open in terminal".

Run the command:

python -m http.server 8000

The terminal shows a message like "Serving HTTP on 0.0.0.0 port 8000". The server is active.

Open your browser and navigate to:

  • Navigator: http://localhost:8000/choicemap.html
  • Scenario Editor: http://localhost:8000/scenario-editor.html
  • Theme Editor: http://localhost:8000/theme-editor.html

To stop the server, return to the terminal and press Ctrl+C.

Why a server is needed

Opening HTML files directly (double-click or dragging to browser), the Navigator doesn't work. A blank screen or error appears.

The reason is a browser security restriction. When an HTML file is opened from the local filesystem (URL starting with file://), the browser prevents loading other files like scenario JSONs. It's a protection against malicious scripts.

The local server bypasses this limitation by serving files via HTTP (URL starting with http://). It's the same protocol used by websites, so the browser allows loading.

This limitation only exists locally. Once published on a web server (GitHub Pages, corporate hosting), everything works normally.

Ports and conflicts

The server uses port 8000 by default. If that port is already occupied by another program, an error appears.

To use a different port:

python -m http.server 8080

Remember to update the address in the browser: http://localhost:8080/choicemap.html.

Folder structure

It's not necessary to keep all files in the same folder, but it simplifies management. The recommended structure is:

choicemap/
├── choicemap.html
├── scenario-editor.html
├── theme-editor.html
├── config.json
├── defaults.json
├── theme.json
├── scenario-my-project.json
├── theme-company.json
└── docs/
    └── (PDF files, resources)

If you prefer to organize differently, for example putting JSON files in a subfolder, you need to update the paths in config.json.