Skip to content
This repository has been archived by the owner on May 2, 2020. It is now read-only.

Commit

Permalink
chore(readme): Update for new Yarn structure and workflow
Browse files Browse the repository at this point in the history 
Also remove to do list, see inexorgame-obsolete/deprecated-cube-engine-inexor#562
  • Loading branch information
@Croydon
Croydon committed Feb 27, 2018
1 parent 38d725e commit f74f9d2
Showing 1 changed file with 42 additions and 60 deletions.
102 changes: 42 additions & 60 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -65,35 +60,36 @@ 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.

After _the "wire"_ individual components, such as the package manager are started.

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:
Expand All @@ -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

Expand All @@ -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

0 comments on commit f74f9d2

Please sign in to comment.