Labyrinth

Content Outline

Motivation
Implementation
Contributions, Bug Reports, Feature Requests
Issue and Branch Policy
How to add new tiles
How to add a new character
How to add a new badge
Hints for GCI students
Solve an Issue
UI identity guideline
Maintainers

This is a labyrinth software which can be edited by you. This is an example in which direction we go:

Our goal is to have contributors draw parts of the labyrinth (Inkscape or hand drawn or other techniques), embed them into a huge labyrinth. Possibly, we can have multiple levels all stuck together.

Motivation

In the past two years, we created Flappy SVG. We had problems coordinating because this is all one SVG file. This time, we can allow contributors to work independently on a level and coordination comes with embedding. This allows remixing of each other's work and thus collaboration in new ways such as:

Adding your tile to an existing labyrinth
Creating your own labyrinth from other tiles.

It is possible to extend the level in various ways: Keys, asking characters in the game, animation, moving through the game, multiple levels. Also, we can create apps, credit pages and various other things with it.

Implementation

This will be an HTML/JS only site. Levels can be created by editing a table specification.

Contributions, Bug Reports, Feature Requests

This is an Open Source project and we would be happy to see contributors who report bugs and file feature requests by submitting pull requests as well. Please report issues in the GitHub tracker.

Issue and Branch Policy

Before making a pull request, please file an issue. So, other developers have the chance to give feedback or discuss details. Match every pull request with an issue please and add the issue number in description e.g. like "Fixes #123".

We have the following branch

master
This contains shipped code. After significant features/bugfixes are accumulated on development, we make a version update, and make a release.

How to add new tiles

Labyrinth allows you to add your tiles by customizing the required javascript and svg files. There are various types of svg files which are available such as doors, floors etc.

Currently the tiles are svg images which are embedded into a div via javascript. Floor tiles have a dimension of about 429.544 x 256.314 px (wxh) Tiles are present in the tiles folder within subdirectories corresponding to particular tiles such as door, floor etc.

To create a tile you may use an svg editor such as inkscape. However other photo editors and formats do wok if they are imported into the editor and saved as a svg file with the speccified dimensions.

After creating tiles add them to the specific sub folder inside tiles.

Now, we will move on to the javascript part. Each tile's attributes and specifications along with it's declaration is done in the js/tiles.js file. You may edit this file defining attributes such as how you could enter and exit out of the tile and so on. You can also specify the door it takes, it's closed exit paths etc. A sample Implementation should go into the already defined door class like:

tile_name: Object.assign({}, OpenDoors, {
    canEnterFromTheRight() {return false;}, /* Don't use this attribute if you do not want the user to enter from right */
    canLeaveToTheRight() {return false;},
    /* Simillarly you can have canLeaveToTheLeft(), canEnterFromTheTop() etc. */
    createImages: function() {
      this.wallTop = this.createImage("tiles/rooms/wall/top.svg"); /* Alter these atrributes to specify a custom wall tile for the floor tile. */
      this.wallRight = this.createImage("tiles/rooms/wall/right.svg");
      this.ground = this.createImage("tiles/rooms/floor/svg_name.svg"); /*  svg_name is the name of your svg */
    },
  }),

If you want to display an alert box when the character reaches your tile, your implementation must be something like this :

tile_name: Object.assign({}, OpenDoors, {
    canEnterFromTheRight() {return false;}, /* Don't use this attribute if you do not want the user to enter from right */
    canLeaveToTheRight() {return false;},
    /* Simillarly you can have canLeaveToTheLeft(), canEnterFromTheTop() etc. */
    createImages: function() {
      this.wallTop = this.createImage("tiles/rooms/wall/top.svg"); /* Alter these atrributes to specify a custom wall tile for the floor tile. */
      this.wallRight = this.createImage("tiles/rooms/wall/right.svg");
      this.ground = this.createImage("tiles/rooms/floor/svg_name.svg"); /*  svg_name is the name of your svg */
    },
    visit: function() {
    alertName("title", "text");
        this.wallTop.show();
        this.wallRight.show();
        this.ground.show();
     },
  }),

Replace alertName with either alertNormal, alertInfo, alertQuestion, alertSuccess, alertError or alertWarning. For more info, read this.

And replace title and text with whatever title or text you want to display. If you want to only have a title and not any text, keep text empty. Like this : "".

After doing so now let's call the tile from the level so that they are reachable. You may modify `/js/levels.js` (which is currently the only level to include your tile. Something like `door.tile_name` since we have added it (our object) to the door (which is a class). You may use css to animate the svg if you wish.

How to Add Music

If you want to have a sound played when the character reaches your tile, your implementation must be something like this:

    visit: function() {
      playAudio("audio.mp3");
      // ...
     },

To add your audio file, please read the following carefully: Audio files are usually not licensed under AGPL. They have a different license. Please make sure that the license permits using the file for the project. Licenses which allow free usage are e.g. the Creative Commons Licenses: CC-BY, CC-BY-SA, CC-BY-NC, ... . To add the a sound file, we need to respect the license, so please follow this guide:

Add your sound file to the audio directory. Use a name which fits the sound.
Add a file with the license of the sound file. If your file is named audio.mp3 add a file named audio.mp3.license.
If you created this sound, please consider adding the source files.

So, these two structures can exist in the audio folder:

A single file with a license:

audio/
+- sound.mp3
+- sound.mp3.license

A folder for many sound files with one license:

audio/
+- source-name/
   +- LICENSE
   +- README.md
   +- sound1.mp3
   +- sound2.ogg

Please note that you can have both audio and alert box in your tile as well.

If you want to add a background music, add your music to audio/background/ in the same way. and update the js/sound.js file like so

const backgroundAudio = [
    {
        filename : "Path of the file",
        backgroundSongName: "Name of the song",
        author: "Name of the author",
        legalNotice : "Music by author",
        link : "Link to author's website",
    },
];

Make sure you comply with the way the person wants this song to be cited and add this to legalNotice in HTML format. This could be the same as the content of the license file for the file.

How to add a new character

Labyrinth allows you to add your characters by customizing the required javascript and svg files.

Currently the characters are svg images which are embedded into a div via javascript. Characters have a dimension of about 55 x 60 px (wxh) Characters are present in the characters folder.

To create a character you may use an svg editor such as inkscape. However other photo editors and formats do wok if they are imported into the editor and saved as a svg file with the speccified dimensions.

After creating characters add them to the characters folder.

Now, we will move on to the javascript part. Each character has only difference in it's appearance and hence can be injected via putting it's name and location to the svg file in gui.js Follow the format while adding to gui.js (To be precise add it to the swal box input values collection i.e, into the inputOptionsPromise variable under the resolve sub class.)

"character_src": "character_name",

How to add a new badge

Players will archieve badge when they reachs a certain tiles, you may allow players to recieve badge when they reached youe tile as well. To create a badge we'll need to upload your badge and modify tiles.js. As for designing the badge itself you may use Inkscape, Adobe Illustrator, or other photo editor, please make sure your badge is in .png format.

First, add your badge to images/game/badges, keep the resolution above ~100px but not above 330px (note that resolution are not dimension) to avoid broken image.

Next, in tiles.js add the following to your tile function;

visit: function() {
        player.badges.add(['badgeName', 'fileName.png']);
        this.wallTop.show();
        this.wallRight.show();
        this.ground.show();
      }

You may add pop-up alert if you'd like, by adding sweet alert, for example;

swal({
                type: 'info',
                title: 'Congrats! You got the DISCOVERER badge',
            });

Hints for GCI students

Adding animated tiles

Download and install Inkscape
Create a tile with the same dimensions as those which are there. Ways of his tile must end at the middle of the edges.
Use CSS to animate the tile in a way: Bird flapping/oven cooking/water dropping, ...
While editing the game you may have ideas for improvement - add them as github issue.
Create a pull-request and have it merged

Adding tiles for landscape

Download and install Inkscape
Create tiles with the same dimensions as those which are there. Ways of his tile must end at the middle of the edges.
Add the tiles to the labyrinth, so they are reachable. Please create a small portion of the labyrinth with them to make it more exciting. You may get inspiration from other parts of the labyinth.
Create a pull-request and have it merged

Creating a hand-drawn landscape

Download and install Inkscape
Create tiles with the same dimensions as those which are there. Ways of his tile must end at the middle of the edges. These tiles must be hand-drawn. A work-flow could be:
1. Draw one tile on a sheet of paper
2. Scan it or photograph it
3. make the unnecessary pixels/sections transparent - you can do that by using a PNG file or by clipping in Inkscape.
Add the tiles to the labyrinth, so they are reachable. Please create a small portion of the labyrinth with them to make it more exciting. You may get inspiration from other parts of the labyrinth.
Create a pull-request and have it merged.

Add a new Pull request after solving a issue

Go to the labyrinth repository.
Go to the issue tab and find a issue that you want to resolve or improve.
Resolve/improve that issue and push those changes into your repo.
Copy the issue number from issue tab.
Go to your forked repository.
Go to Pull Reqest tab.
Click on New pull request.
See there all files changes are ready or not(If not not follow next steps, please add your changes before proceed).
Select base fork and head fork if it isn't not selected automatically.
Click on Create Pull request.
Change PR topic and message as instructions on it.
Then click on create pull request. Now your pull request is ready! See on Pull requests

Solve an Issue

The FOSSASIA Labyrinth allows you to contribute parts to a huge labyrinth. Please improve the game by solving an issue.

Comment on an issue that you want to do it. If you have solved several tasks on this game before, you can not claim tasks that are too easy for you because we need them to give others an easy start.
Get assigned to the issue you work on, so other people coordinate with you. Being assigned an issue does not mean you can block progress by not answering.