From f74f9d2f51ea6694dde4b2f0ac9b95b38173779c Mon Sep 17 00:00:00 2001 From: Croydon Date: Tue, 27 Feb 2018 13:21:27 +0100 Subject: [PATCH] chore(readme): Update for new Yarn structure and workflow Also remove to do list, see inexorgame/inexor-core#562 --- README.md | 102 ++++++++++++++++++++++-------------------------------- 1 file changed, 42 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index 3a468d6..2d04bdf 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,56 @@ # Inexor Flex -[![npm version](https://badge.fury.io/js/%40inexorgame%2Finexor-flex.svg)](https://badge.fury.io/js/%40inexorgame%2Finexor-flex) [![Build Status](https://travis-ci.org/inexorgame/inexor-flex.svg?branch=master)](https://travis-ci.org/inexorgame/inexor-flex) [![Build status](https://ci.appveyor.com/api/projects/status/55kpm71yyetbcpag?svg=true)](https://ci.appveyor.com/project/inexorgame/inexor-flex) [![Dependency Status](https://dependencyci.com/github/inexorgame/inexor-flex/badge)](https://dependencyci.com/github/inexorgame/inexor-flex) [![NSP Status](https://nodesecurity.io/orgs/inexorgame/projects/c53b7d61-a945-44a0-9678-2e555f0c4303/badge)](https://nodesecurity.io/orgs/inexorgame/projects/c53b7d61-a945-44a0-9678-2e555f0c4303) +[![package version](https://badge.fury.io/js/%40inexorgame%2Finexor-flex.svg)](https://badge.fury.io/js/%40inexorgame%2Finexor-flex) [![Build Status](https://travis-ci.org/inexorgame/inexor-flex.svg?branch=master)](https://travis-ci.org/inexorgame/inexor-flex) [![Build status](https://ci.appveyor.com/api/projects/status/55kpm71yyetbcpag?svg=true)](https://ci.appveyor.com/project/inexorgame/inexor-flex) [![Dependency Status](https://dependencyci.com/github/inexorgame/inexor-flex/badge)](https://dependencyci.com/github/inexorgame/inexor-flex) [![NSP Status](https://nodesecurity.io/orgs/inexorgame/projects/c53b7d61-a945-44a0-9678-2e555f0c4303/badge)](https://nodesecurity.io/orgs/inexorgame/projects/c53b7d61-a945-44a0-9678-2e555f0c4303) Inexor Flex is platform for managing [Inexor Core](https://github.com/inexorgame/inexor-core) instances and the Inexor Tree API and provides a scripting environment for servers and clients. Inexor Flex also makes multiple user interfaces using web technologies available. The reference documentation can be found at [GitHub pages](https://inexorgame.github.io/inexor-flex) Further introduction and overview: https://github.com/inexorgame/inexor-core/wiki/Inexor-Flex -## Introduction -Hello there and welcome to the `inexor-flex` documentation! - -Now, you're wondering what `inexor-flex` actually is, and what it does? -Below is a brief explanation about `inexor-flex`: +## Introduction - we wanted to create a way in which we can easily configure and extend our game - that's why we created _the `tree`_. It means that all the settings (variables) in the game can be edited in real-time in a tree structure - but this tree was hard to access. It's sent over the wire in a compressed format, that's hard to work with for _"casual users"_ - next: we created `inexor-flex`. It makes this tree available via a web service (and webviewer). On your local computer. -- not only can you edit the game in real time with `flex`, it also does a bunch of things for you +- not only can you edit the game in real time with `inexor-flex`, it also does a bunch of things for you - read configuration. e.g for maps, or servers - read the server list - only your imagination is the limit (...) -## How to set up inexor-flex -You can choose from one of our graphical installers [at our website](https://inexor.org/download). - -If you're a little bit more of a techy, here are the command line instructions to install flex +## How to set up Flex - you need to have `Node.js` installed from [nodejs.org](nodejs.org). The latest stable release is recommended. -- open a terminal/shell -- install the `yarn` package manager via `npm i -g yarn` -- install flex via `yarn i -g @inexorgame/inexor-flex` -- you can start flex via `inexor-flex` directly at your fingertips +- install the [Yarn package manager](https://yarnpkg.com/en/docs/install) + +If you **don't want to contribute to Flex itself**, you can install it via +- `yarn global add @inexorgame/inexor-flex` +- now you can start Flex via `inexor-flex` _NOTE:_ If you're curious what the graphical installer does. No suprise. Exactly the same. +If you are **considering to contribute to Flex**: + +- clone this repository +- open a terminal/shell within the Flex repository directory +- install Flex via `yarn install` +- you can start Flex via `yarn start` + + ## What's this _"instances"_ thing? Since nowadays, all configuration is done via `inexor-flex`, we have introduced a system called `instances`. -Each Inexor client or server is an instance. You can have multiple clients (or servers), with different configurations, even running different versions of the game. No problemo. +Each Inexor client or server is an instance. You can have multiple clients (or servers), with different configurations, even running different versions of the game. + ## Now let's go fancy. Right at your browser. If you want to be little bit more of a power user, we also ship a graphical interface for flex. Right there. When you download it. Just go to [http://localhost:31416/api/v1/interfaces/ui-flex](http://localhost:31416/api/v1/interfaces/ui-flex) -And even more fancy. You can see the `inexor tree` at [http://localhost:31416/api/v1/interfaces/ui-flex/#/instances/31417](http://localhost:31416/api/v1/interfaces/ui-flex/#/instances/31417) - -# Developer section +And even more fancy. You can see the `Inexor Tree` at [http://localhost:31416/api/v1/interfaces/ui-flex/#/instances/31417](http://localhost:31416/api/v1/interfaces/ui-flex/#/instances/31417) -## How to set up inexor-flex as a developer -To set up `inexor-flex` follow the below instructions. -Given that you have cloned `inexor-flex` and are in the `inexor-flex` directory: -``` -yarn install -yarn start # start flex -``` +# Developer section ### The command line `inexor-flex` brings a verbose command line that can easily be accessed with it's name. @@ -65,8 +60,8 @@ Just call `inexor-flex` from your command line (shell, prompt, terminal), and yo Flex is structure in two main folders: -- `src` is where the utilities of flex reside -- `server` is where the actual `flex server` resides. The web server is started here, and all run-time functionality (such as paths) are determined here. +- `src` is where the utilities of Flex reside +- `server` is where the actual `Flex server` resides. The web server is started here, and all run-time functionality (such as paths) are determined here. All of the above components are wired together using the [Application Context](https://inexorgame.github.io/inexor-flex/src_context_index.js.html) module. @@ -74,26 +69,27 @@ After _the "wire"_ individual components, such as the package manager are starte The API is exposed as a [RESTfull API](https://en.wikipedia.org/wiki/Representational_state_transfer). + ### Architectual -`inexor-flex` was initially born to serve the tree of `inexor-core` and this is how it works nowadays. +Inexor Flex was initially born to serve the tree of Inexor Core and this is how it works nowadays. -- we create a _mother inexor_ root node using the `@inexorgame/tree` module +- we create a _mother Inexor_ root node using the `@inexorgame/tree` module - each instance of Inexor Core has a `src/instances/Connector` attached - this Connector will create a tree at `/instance/INSTANCEID` - other modules can be hooked in other namespaces than `/instances`. e.g for the ReleaseManager, the namespace is `/releases` + ### Interfaces -Interfaces are graphical user interfaces for `inexor-flex` *and* `inexor-core`. -An interface is basically just a HTML5/CSS/JavaScript folder, which will be made available via the REST API. +Interfaces are graphical user interfaces for Inexor Flex *and* Inexor Core. +An interfaces is basically just HTML5/CSS/JavaScript folders, which will be made available via the REST API. -Below is a list of the default interfaces shipped with `inexor-flex`: +Below is a list of the default interfaces shipped with Flex: - [ui-flex](https://github.com/inexorgame/ui-flex) is used to manage the flex server itself - [ui-console](https://github.com/inexorgame/ui-console) is an interactive console for the game - [ui-client-hud](https://github.com/inexorgame/ui-client-hud) is a HUD system for the game - [ui-client-interface](https://github.com/inexorgame/ui-client-interface) are the menu(s) for the game -*NOTE:* For the `ui` modules also uses `yarn` #### Adding an own interface An interface should follow the below directory structure: @@ -111,11 +107,12 @@ An interface should follow the below directory structure: You can then use the `interfaces` command line to add your newly written. + ### Documentation and style guide We use [JSDoc](http://usejsdoc.org/) for documentation. All modules from `src` and `server` are automatically added to the documentation, when following the standards. We endorse the [`eslint:recommended`](https://eslint.org/docs/rules/) rule set, combined with some custom rules. -You can make sure your module matches our standard by running `npm run lint` in the main directory. +You can make sure your module matches our standard by running `yarn run lint` in the main directory. When writting a module, please keep the following in mind @@ -125,44 +122,29 @@ When writting a module, please keep the following in mind We also try to apply the changes detected by the [`security/recommended`] standard. + ### The REST API -The REST API (`v1`) is wired together in `server/api/v1/index.js` -Documentation via [swagger](https://swagger.io/) should follow soon enough. +The REST API (`v1`) is wired together in `server/api/v1/index.js`. + ### Writing an own module Essentially to write your very first own module, you should go like this -- `mkdir src/YOURMODULE` -- `cd src/YOURMODULE & npm init` which will ask you a bunch of questions -- the name of your module should ideally be `@inexorgame/YOURMODULE` +- create a new directory `src/YOURMODULE` +- execute `yarn init` within your module directory, which will ask you a bunch of questions +- the name of your module has to be `@inexorgame/YOURMODULE` - your module should export a `index.js` file with it's functionality +- **YOU HAVE TO** add your new module to the `fileDependencies` in the root `package.json` +- after this execute `yarn install` again within the root directory -Now you can use `npm link` inside the directory. Later on your module can be used via +Later on your module can be used via ``` const yourmodule = require('@inexorgame/yourmodule') ``` You can have a look at the `src/types` module, for a very simple and basic module example. + #### Using the API We have specifically designed the module `@inexorgame/treeclient` to work with the `v1` API. You can have a look at one of the many command-line tasks in `server/commands/cli/` which will give a fine example on how to use the `treeclient` library. - -### Flex won't start. Resolving conflicts with the module manager -If `flex` won't start for strange reasons the most likely thing is that you've worked with a earlier revision in which an individual module is broken. -Try the following: - -`npm unlink @inexorgame && npm un -g @inexorgame/inexor-flex` -`rm -rf node_modules` -And then install again. - - -### Future features -This is either to-do or nice to have - -- [ ] add example modules and user documentation a-la readthedocs -- [ ] test everything extensively, fix passages that are marked with TODO (and add unit tests!) -- [ ] authentication via OAuth -- [ ] more secure server -- [ ] sandbox-based plugin system -- [ ] server lister and package lister