README.md

   1 # LibreAdventure
   2
   3 LibreAdventure is a fork of the last freely licensed version of
   4 WorkAdventure, plus a map and small changes for use at LibrePlanet 2021/2022.
   5 Renaming is incomplete.
   6
   7 At FSF, we mainly want to fix a bug for LibrePlanet 2022
   8 (https://todo.sr.ht/~iank/libreadventure/1), and if we can find some
   9 other improvements to make that would be good too.
  10
  11 #fsfsys on libera.chat and the SourceHut mailing list for this project
  12 are the main place to ask questions and coordinate. Yes, we know there
  13 are little to no posts on the mailing list yet, don't let that stop you.
  14
  15 There exists an instance of this code at an FSF server,
  16 play.libreadventure.org. If you want to help with LibreAdventure, FSF
  17 tech team is giving access to test changes there to people they think are
  18 trustworthy (they have done some work volunteering or something). If you
  19 think you one of those people, email <sysadmin@fsf.org> with your public
  20 ssh key and join
  21 #fsfsys and say that you've emailed your key and want to help with
  22 LibreAdventure.  The FSF tech team will add your key to the server.
  23 Before making changes to the server please say something on #fsfsys in
  24 order to make coordinate with any other volunteer who may be working on
  25 it. The main way to run the software on the FSF server is with `cd
  26 /srv/libreadventure-deployment; docker-compose restart`, then browse to
  27 https://play.libreadventure.fsf.org. The standard out of docker-compose
  28 is useful for development, so if multiple people want to work on it at
  29 the same time, you will probably need to coordinate to make it visible
  30 to multiple people, like sharing an tmux or screen, or redirecting it to
  31 a log file that can be tailed.
  32
  33 Feel free to have a look at the upstream version of WorkAdventure and
  34 explore improvements made there. We should not copy any code because the
  35 upstream is under an incompatible license.
  36
  37 This package is licensed AGPLv3. There is no indication in the repo of
  38 whether the original authors meant AGPLv3 or later or only. We are
  39 waiting to hear from them. Any contribution you make is assumed to be
  40 dual licensed AGPLv3 only and AGPLv3 or later, so that when the original
  41 license gets clarified, we will distribute under that.
  42
  43
  44 # Work Adventure (upstream readme is below)
  45
  46 ## Work in progress
  47
  48 Work Adventure is a web-based collaborative workspace for small to medium teams (2-100 people) presented in the form of a
  49 16-bit video game.
  50
  51 In Work Adventure, you can move around your office and talk to your colleagues (using a video-chat feature that is
  52 triggered when you move next to a colleague).
  53
  54
  55 ## Getting started
  56
  57 Install Docker.
  58
  59 Run:
  60
  61 ```
  62 docker-compose up
  63 ```
  64
  65 The environment will start.
  66
  67 You should now be able to browse to http://workadventure.localhost/ and see the application.
  68
  69 Note: on some OSes, you will need to add this line to your `/etc/hosts` file:
  70
  71 **/etc/hosts**
  72 ```
  73 workadventure.localhost 127.0.0.1
  74 ```
  75
  76 ## Designing a map
  77
  78 If you want to design your own map, you can use [Tiled](https://www.mapeditor.org/).
  79
  80 A few things to notice:
  81
  82 - your map can have as many layers as you want
  83 - your map MUST contain a layer named "floorLayer" of type "objectgroup" that represents the layer on which characters will be drawn.
  84 - the tilesets in your map MUST be embedded. You cannot refer to an external typeset in a TSX file. Click the "embed tileset" button in the tileset tab to embed tileset data.
  85 - your map MUST be exported in JSON format. You need to use a recent version of Tiled to get JSON format export (1.3+)
  86 - WorkAdventure doesn't support object layers and will ignore them
  87 - If you are starting from a blank map, your map MUST be orthogonal and tiles size should be 32x32.
  88
  89 ![](doc/images/tiled_screenshot_1.png)
  90
  91 ### Defining a default entry point
  92
  93 In order to define a default start position, you MUST create a layer named "start" on your map.
  94 This layer MUST contain at least one tile. The players will start on the tile of this layer.
  95 If the layer contains many tiles selected, the players will start randomly on one of those tiles.
  96
  97 ### Defining exits
  98
  99 In order to place an exit on your scene that leads to another scene:
 100
 101 - You must create a specific layer. When a character reaches ANY tile of that layer, it will exit the scene.
 102 - In layer properties, you MUST add "exitSceneUrl" property. It represents the map URL of the next scene. For example : `/<map folder>/<map>.json`. Be careful, if you want the next map to be correctly loaded, you must check that the map files are in folder `back/src/Assets/Maps/<your map folder>`. The files will be accessible by url `<HOST>/map/files/<your map folder>/...`.
 103 - In layer properties, you CAN add an "exitInstance" property. If set, you will join the map of the specified instance. Otherwise, you will stay on the same instance.
 104 - If you want to have multiple exits, you can create many layers with name "exit". Each layer has a different key `exitSceneUrl` and have tiles that represent exits to another scene.
 105
 106 ![](doc/images/exit_layer_map.png)
 107
 108 ### Defining several entry points
 109
 110 Often your map will have several exits, and therefore, several entry points. For instance, if there
 111 is an exit by a door that leads to the garden map, when you come back from the garden you expect to
 112 come back by the same door. Therefore, a map can have several entry points.
 113 Those entry points are "named" (they have a name).
 114
 115 In order to create a named entry point:
 116
 117 - You must create a specific layer. When a character enters the map by this entry point, it will enter the map randomly on ANY tile of that layer.
 118 - In layer properties, you MUST add a boolean "startLayer" property. It should be set to true.
 119 - The name of the entry point is the name of the layer
 120 - To enter via this entry point, simply add a hash with the entry point name to the URL ("#[*startLayerName*]"). For instance: "https://workadventu.re/_/global/mymap.com/path/map.json#my-entry-point".
 121 - You can of course use the "#" notation in an exit scene URL (so an exit scene URL will point to a given entry scene URL)
 122
 123
 124 ### MacOS developers, your environment with Vagrant
 125
 126 If you are using MacOS, you can increase Docker performance using Vagrant. If you want more explanations, you can read [this medium article](https://medium.com/better-programming/vagrant-to-increase-docker-performance-with-macos-25b354b0c65c).
 127
 128 #### Prerequisites
 129
 130 - VirtualBox*   5.x     Latest version  https://www.virtualbox.org/wiki/Downloads
 131 - Vagrant       2.2.7   Latest version  https://www.vagrantup.com/downloads.html
 132
 133 #### First steps
 134
 135 Create a config file `Vagrantfile` from `Vagrantfile.template`
 136
 137 ```bash
 138 cp Vagrantfile.template Vagrantfile
 139 ```
 140
 141 In `Vagrantfile`, update `VM_HOST_PATH` with the local project path of your machine.
 142
 143 ```
 144 #VM_HOST_PATH# => your local machine path to the project
 145
 146 ```
 147
 148 (run `pwd` and copy the path in this variable)
 149
 150 To start your VM Vagrant, run:
 151
 152 ```bash
 153 Vagrant up
 154 ```
 155
 156 To connect to your VM, run:
 157
 158
 159 ```bash
 160 Vagrant ssh
 161 ```
 162
 163 To start project environment, run
 164
 165 ```bash
 166 docker-compose up
 167 ```
 168
 169 You environment runs in you VM Vagrant. When you want stop your VM, you can run:
 170
 171 ````bash
 172 Vagrant halt
 173 ````
 174
 175 If you want to destroy, you can run
 176
 177 ````bash
 178 Vagrant destroy
 179 ````
 180
 181 #### Available commands
 182
 183 * `Vagrant up`: start your VM Vagrant.
 184 * `Vagrant reload`: reload your VM Vagrant when you change Vagrantfile.
 185 * `Vagrant ssh`: connect on your VM Vagrant.
 186 * `Vagrant halt`: stop your VM Vagrant.
 187 * `Vagrant destroy`: delete your VM Vagrant.
 188
 189 ## Features developed
 190 You have more details of features developed in back [README.md](./back/README.md).