+
+
| Sub-block | +Direction | +
| Center | +- | +
| Top | ++Y axis | +
| Bottom | +-Y axis | +
| Front | +-Z axis | +
| Back | ++Z axis | +
| Left | +-X axis | +
| Right | ++X axis | +
` to separate different paragraphs. Note that you are not allowed to use self-closing tags, e.g., `
`. Place a single `` tag on the blank line between paragraphs: + +```java + /** + * First paragraph. + *
+ * Second paragraph. + * May be on multiple lines. + *
+ * Third paragraph. + */ + public ... +``` + +Lists are useful in Javadoc when explaining a set of options, choices or issues. These standards place a single `
-
+ *
- the first item + *
- the second item + *
- the third item
+ *
+ * Second paragraph. + */ + public ... +``` + +### @code and @link +Many Javadoc descriptions reference other methods and classes. This can be achieved most effectively using the @link and @code features. + +The @link feature creates a visible hyperlink in generated Javadoc to the target. The @link target is one of the following forms: + +```java + /** + * First paragraph. + *
+ * Link to a class named 'Foo': {@link Foo}. + * Link to a method 'bar' on a class named 'Foo': {@link Foo#bar}. + * Link to a method 'baz' on this class: {@link #baz}. + * Link specifying text of the hyperlink after a space: {@link Foo the Foo class}. + * Link to a method handling method overload {@link Foo#bar(String,int)}. + */ + public ... +``` + +The @code feature provides a section of fixed-width font, ideal for references to methods and class names. While @link references are checked by the Javadoc compiler, @code references are not. + +Only use @link on the first reference to a specific class or method. Use @code for subsequent references. This avoids excessive hyperlinks cluttering up the Javadoc. + +Do not use @link in the punch line. The first sentence is used in the higher level Javadoc. Adding a hyperlink in that first sentence makes the higher level documentation more confusing. Always use @code in the first sentence if necessary. @link can be used from the second sentence/paragraph onwards. + +Do not use @code for null, true or false. The concepts of null, true and false are very common in Javadoc. Adding @code for every occurrence is a burden to both the reader and writer of the Javadoc and adds no real value. + +### @param, @return, and @throws + +Almost all methods take in a parameter, return a result or both. The @param and @return features specify those inputs and outputs. The @throws feature specifies the thrown exceptions. The @param entries should be specified in the same order as the parameters. The @return should be after the @param entries, followed by @throws. + +Use @param for generics. If a class or method has generic type parameters, then these should be documented. The correct approach is an @param tag with the parameter name of <T> where T is the type parameter name. + +Use one blank line before @param. There should be one blank line between the Javadoc text and the first @param or @return. This aids readability in source code. + +The @param and @return should be treated as phrases rather than complete sentences. They should start with a lower case letter, typically using the word "the". They should not end with a dot. This aids readability in source code and when generated. + +Treat @throws as an if clause. The @throws feature should normally be followed by "if" and the rest of the phrase describing the condition. For example, "@throws if the file could not be found". This aids readability in source code and when generated. + +**To discuss:** use a single space after @param or indent to common column? + +### @author + +By convention we avoid the `@author` tag. It will generally go out of date, and can promote code ownership by an individual. The source control system is in a much better position to record authors. + +### Document All Public and Protected + +All public and protected methods should be fully defined with Javadoc. Especially complex methods, procedures with side-effects, and non-trivial operations should be documented well. Package and private methods do not have to be, but may benefit from it. + +### null-tolerance, Pre- and Postconditions + +Whether a method accepts null on input, or can return null is critical information for building large systems. All non-primitive methods should define their null-tolerance in the @param or @return. Some standard forms expressing this should be used wherever possible: + +* "not null" means that null is not accepted and passing in null will probably throw an exception , typically NullPointerException +* "may be null" means that null may be passed in. In general the behaviour of the passed in null should be defined +* "null treated as xxx" means that a null input is equivalent to the specified value +* "null returns xxx" means that a null input always returns the specified value + +When defined in this way, there should not be an @throws for NullPointerException. + +```java + /** + * Javadoc text. + * + * @param foo the foo parameter, not null + * @param bar the bar parameter, null returns null + * @return the baz content, null if not processed + */ + public String process(String foo, String bar) {...} +``` + +While it may be tempting to define null-handling behavior in a single central location, such as the class or package Javadoc, this is far less useful for developers. The Javadoc at the method level appears in IDEs during normal coding, whereas class or package level Javadoc requires a separate "search and learn" step. + +Other simple constraints may be added as well if applicable, for example "not empty, not null". Primitive values might specify their bounds, for example "from 1 to 5", or "not negative". + +### Generating it + +To generate Javadoc for the project simply execute `gradle javadoc` at the root of the project. The actual `build.gradle` doesn't need to have any related scripting in it, the Javadoc Gradle plugin does it all! diff --git a/docs/Codebase-Structure.md b/docs/Codebase-Structure.md new file mode 100644 index 00000000000..6be606a995a --- /dev/null +++ b/docs/Codebase-Structure.md @@ -0,0 +1,144 @@ +This is an overview of the different parts of our primary codebase and will be primarily of interest to developers/modders. See also [Project Overview](Project-Overview.md) for a higher level view across more different projects. + +Gradle +--------- + +Most of our projects are organized using [Gradle](http://www.gradle.org), a build automation tool similar to [Maven](http://maven.apache.org), but using [Groovy](http://groovy.codehaus.org) as its language. This allows for some pretty powerful scripting and customization of a local developer setup while leveraging maven repositories for dependency resolution. + +You interact with Gradle using a "gradlew" wrapper script that downloads and installs the correct project-specific version of Gradle itself. No need to install anything locally yourself. You simply run the command "gradlew" on any OS in the directory you've cloned the primary Terasology engine repo to and the correct version will be fetched and executed. + +Gradle works great with multiple sub-projects and builds a "project tree" before any functional work begins. This is great for dealing with dependencies but does also mean that if the project structure changes on one execution (such as when fetching a new module from GitHub) the new sub-project will only be included on the next execution. + +As you work on Terasology you might find out that you need source or binaries for other sub-projects, which can then be added easily to your existing workspace through an assortment of Gradle tasks. Keep reading to learn more. + +Note: On Linux and Mac OS you may have to first mark the "gradlew" file as executable. + +To speed up gradle on linux add org.gradle.daemon=true to ~/.gradle/gradle.properties + + +Engine +--------- + +The heart and soul of Terasology. All facades and modules depend on the engine. + +The primary repo containing the engine is the first and only thing you need to run the game and allows you to use Gradle commands to fetch everything else. Always assume you need to execute "gradlew" from the root directory of this project unless stated otherwise. This is the one repo you need to clone manually: + +`git clone https://github.com/MovingBlocks/Terasology.git` + +Along with the engine you get the PC Facade and a few embedded modules. Everything else lives in independent GitHub repos that can be added to your local workspace as sub-projects. You can edit several at once, commit files across multiple Git roots, and push it all to each affected repo on GitHub in one action. + +It also comes with several utility tasks, such as project file generation for [IDEA IntelliJ](http://www.jetbrains.com/idea). This is our recommended IDE (with a [freebie Ultimate Edition available](http://forum.movingblocks.net/threads/how-to-use-this-forum.33/#post-8778) for contributors) and the customized setup for it is fairly detailed. + +You can also use [Eclipse](http://www.eclipse.org/), [NetBeans](https://netbeans.org/), or anything else you like, but you might have to figure out some of the setup details yourself - and if you do please post them in the [forum](http://forum.movingblocks.net/forums/developer-portal.5/) so we can improve the instructions to set up with alternative IDEs :-) + +IntelliJ (versions 2020.1 and newer) will load the configuration from gradle after you "Import Gradle Project." The portions of the project configuration not detected from gradle are stored in the `/.idea` directory. + +The configuration includes: + +* Several run configurations including "TerasologyPC" will be created and immediately be available for execution. These run configurations includes memory settings and the "--homedir" parameter that makes game data files save in the install directory rather than the data directory (easier for development) +* Checkstyle integration with IntelliJ will be enabled. This allows you to catch style violations that clash with the project conventions. Please check these before committing :D +* You'll be able to automatically insert the Project Header (copyright etc) in new files (TODO: More details) +* Annotations, which are used extensively in the project, will get some special consideration when IntelliJ looks at whether code is used or not + +The biggest architectural piece of the engine is our [Entity System](Entity-System-Architecture.md) which powers just about everything, much more than just creatures (typically considered "movable entities" or "mobs") + + +Facades +--------- + +The engine alone is not executable. It needs to run in some sort of context - "facades" (front-ends) supply that by wrapping the engine. + +The most basic one is the "PC Facade" which simply runs the game normally as an application on Windows, Linux, or Macs. This facade is bundled with the engine repo and available right out of the box. + +Another one runs the headless game server with added functionality meant to be used from a website (such as chat or a world map). To be able to work with a separate facade you can fetch it automatically: + +`groovyw facade get FacadeServer` + +Facades are hosted in the MovingBlocks organization on GitHub and have their own custom build scripts. + +Rarely should a new facade be needed, one could be made with: + +`groovyw facade create DevFacade` + +This would create a "facades/DevFacade" sub-project initialized with a few template files and its own Git repo + +Modules +--------- + +If the heart of Terasology is the engine and the facades make up its different faces then the content modules are the different organs - delicious! + +While usually "mods" are user-created modifications to a game our modules are a little more fundamental. Modules are containers for code and assets that can be used by game types, mods or other higher-level concepts. Even the systems and various bits of content in the base game are stored in modules that can be enabled, disabled, or replaced. + +Modules have access to a limited part of the engine through the Modding API. Each is sandboxed for security. Other than the few engine-embedded modules (which will eventually go away) the modules do not get their own custom build file, instead a template is copied in that builds all modules equally. If you change that instance of the file you can refresh all generated module build files with: + +`groovyw module refresh` + +A module can define a "Gameplay Template" which is similar to a "modpack". Several such modes are also supplied in the base game like "JoshariasSurvival" which offers some basic survival with a small tech tree. + +Your workspace starts with very few modules. Here's an example that fetches JoshariasSurvival module and *all* its dependencies as source: + +`groovyw module recurse JoshariasSurvival` + +On the next execution of Gradle the new module will be detected and scanned. If it has dependencies on other modules not yet present then Gradle will attempt to resolve them. + +* Does the dependency exist as another local source module? If so then use that. +* If not then look for a local binary version present in the modules directory. If you later fetch a source module the binary version will be ignored. +* If a dependency is still not found go to our Artifactory instance and look there. If found the binary is copied to the local modules directory to be available at runtime. This will resolve as a local binary next time. + +You can update all your modules to the latest source via the command: + +`groovyw module update-all` + +You can also create a brand new module and have it filled in with some template content: + +`groovyw module create MyNewModule` + +This would create "modules/MyNewModule" and initialize a new Git repo for it locally. + +After the next Gradle execution (like "gradlew idea" to regenerate IntelliJ files to know about the new module) you can immediately run the game and see the new module available. It won't do much yet though! + +For more on modules see: + +* [Module.txt](Module.txt.md) the manifest for a module. Includes description stuff, author info, dependencies, etc. +* [Module Versioning](Release-Modules.md#versioning) +* [Semantic Versioning](http://semver.org) (SemVer). +* Modding Guide +* [Gestalt Modules](https://github.com/MovingBlocks/gestalt/wiki/Modules) - In-depth discussion of Modules (non-Terasology-specific) + +Libraries +--------- + +`libs/` is a directory you can use for including [Locally Developed Libraries](Using-Locally-Developed-Libraries.md). + +Other File Types +--------- + +Beyond code, we have a few major groups of files + +* **Game assets** - actual content used by the game. Might be textures, block shapes, models, etc. See Asset Types for more information. +* **[Protobuf](http://code.google.com/p/protobuf)** - this is a framework for structured data provided by Google. It is used to store data in a binary format for efficient transfer over network connection. +* **Module manifests** - as mentioned above. Each module has a manifest that describes it and any dependencies it has. This includes versioning information. + +We heavily use [JSON](http://www.json.org/) throughout our projects to store text data / assets, configuration, meta-data, and so on. Rather than using json as the file extension, each asset uses an extension relevant to what it is, such as: + +* `.block` = Block definition files. See Block Architecture for more details. Might be outdated at the moment though :-( +* `.shape` = Defines a 3d shape that a block may have. These can be exported from Blender using a bundled addon. +* `.prefab` = "Prefabricated" object, a recipe for creating entities in our entity system. They can also be used to define static information without generating an entity. +* `.texinfo` = Added configuration for how textures should behave. + +Common Issues and Other Notes +--------- + +* If your command window loses focus while working on something that'll pop up an SSH passphrase prompt it may load in the background and be easy to miss. This can leave you with an incomplete sub-project dir + * Incomplete or otherwise corrupt nested git directories (modules, facades ..) may cause trouble, such as complaining about "cannot find task 'classes' on [name]". When in doubt: Delete and fetch again + * Same issue may cause tasks to think you already have a particular module locally - again just delete the partial directory and try again +* If you get compile errors on trying to run with the provided configuration immediately after setting up IntelliJ try doing a full Project Rebuild (may be a poor dependency order compilation issue - or IntelliJ just hasn't finished its initial background build) + +Related Pages +--------- + +* [Contributor Quick Start Guide](Contributor-Quick-Start.md) +* [Code Conventions](Code-Conventions.md) +* [Modding API](Modding-API.md) +* [Entity System Architecture](Entity-System-Architecture.md) +* [Shape Architecture](Block-Shapes.md) diff --git a/docs/Component-Types.md b/docs/Component-Types.md new file mode 100644 index 00000000000..8e85ae672e9 --- /dev/null +++ b/docs/Component-Types.md @@ -0,0 +1,58 @@ +Components are data objects that define the state of an entity and can optionally provide configuration information. They are used by engine and module systems to determine behaviors to apply. Components can be added and removed statically to prefabs or dynamically to entities in-game. + +Components extend the entity component system (ECS) by explicit means of providing state and configuration data. +You can find components everywhere in the code base - they inform, for instance, about blocks being damaged, audio files to be played for footsteps, or the contents of the player's starting inventory. + +> :construction: **_Note, this concept page is currently still under construction. This means that the elaborated concepts and their details are still subject to change until further notice._** + +> _**TODO:** Component fields or entire components are "owned" by a module-internal system that is responsible for managing the field or component._ + +> _**TODO:** Generally, we advise to use topic components to group together related configuration and state information. Separating individual aspects into dedicated components can be useful to allow event receivers to filter which events to process. Before separation, it is advised to consider whether the filtering can also be achieved with a combination of already existing components. For example, ..._ + +We can categorize events by the data they contain. + +- [Marker Components](#marker-components) +- [Configuration Components](#configuration-components) +- [Topic Components](#topic-components) + +Furthermore, components can be _internal_. Internal components should only be managed by their associated system. Any write accesses from module-external systems should be avoided. + +## Marker Components + +> Yo btw, that thing is in a state! + +A _marker component_ represents a single binary information. It marks an entity as having a certain property or state. This information can be used by systems to inform about which actions to take for this entity. If the component is not present, the entity does not have the respective property or state (yet or anymore). + +An example for a marker component are blocks or block-like entities being in a damaged state (`BlockDamagedComponent`). + +**Marker components _do not contain configuration or further state_.** +Marker components are intended to act as indicators of one specific property or state. +As such, they are not expected to provide any additional configuration or state data. + +## Configuration Component + +> Hey, this thing should look and act like that. + +A _configuration component_ stores settings or parameters that can be modified by the player or the game itself. +Systems apply these settings or parameters to the in-game representation of the entity. + +Examples for configuration components are setting the non-technical name of an entity that will be displayed to the player (`DisplayNameComponent`) or configuring the sound to play when the player interacts with the entity (`PlaySoundActionComponent`). + +**Configuration components only contain _configuration data_.** +Configuration components are intended to provide specific settings and parameters for an entity. +They are not expected to provide state data. + +## Topic Components + +> Here's all relevant data about that topic. + +A _topic component_ combines configuration and state data to provide systems with all the data they need. +It groups data relevant for a specific topic into a single component. + +An example for a topic component is the `HealthComponent` which contains both, the maximum and current health of an entity. +While maximum health is configuration data that for instance allows to determine when the entity is fully healed again, the current health is state data that, when compared to maximum health, allows a system to determine whether or not an entity is damaged or even needs to be destroyed. + +--- + + +[entity]: Glossary.md#entity \ No newline at end of file diff --git a/docs/Contributor-Quick-Start.md b/docs/Contributor-Quick-Start.md new file mode 100644 index 00000000000..1125e5219de --- /dev/null +++ b/docs/Contributor-Quick-Start.md @@ -0,0 +1,82 @@ +## Required Knowledge + +* [Git Basics](https://git-scm.com/docs/gittutorial) - We use Git for version control, so you should be familiar with the concept of branches, fetching and committing changes, and pushing to a code repository. +* [GitHub Basics](https://docs.github.com/en/get-started/quickstart/hello-world) - We host our code on and collaborate via GitHub, so you should be familiar with repositories, pull requests, and [forks](https://docs.github.com/en/github/collaborating-with-pull-requests/working-with-forks/about-forks). +* [Bash Basics](https://towardsdatascience.com/basics-of-bash-for-beginners-92e53a4c117a)[0](#f0) - While you can avoid the command-line in most situations, in some situations you'll need to use it, for instance to fetch additional modules into or update your workspace. Especially, any `groovyw` or `gradlew` commands you find in our documentation need to be executed from the command-line. + + +## Required Tools + +* Java 11 JDK (e.g. [OpenJDK 11 from AdoptOpenJDK](https://adoptopenjdk.net/releases.html?variant=openjdk11&jvmVariant=hotspot)) +* Git Client (e.g. [Git for Windows](https://gitforwindows.org/) or [GitKraken](https://www.gitkraken.com/))[1](#f1) +* IDE (e.g. [IntelliJ](https://www.jetbrains.com/idea/download)[2](#f2)) + + +## Set up your Terasology Development Workspace + +1. Clone https://github.com/MovingBlocks/Terasology to a local workspace +1. Change into the new "Terasology" directory +1. Grab our module foundation ("iota" line-up)[3](#f3) + * `groovyw module init iota`[4](#f4) +1. (Optional) Open your workspace directory into IntelliJ; choose "Import Gradle Project" if prompted. + * _Note: Simply open the directory, don't pick "New Project". Our Gradle config will setup the project for you._ +1. Compile and start Terasology from source for the first time + * On the command-line, use `gradlew game` + * In IntelliJ, run the "TerasologyPC" run configuration +1. Select the "CoreSampleGameplay" gameplay +1. Start the game + + +## Start a Custom Basic Gameplay + +1. Grab additional modules and their dependencies + * `groovyw module recurse
` will fetch all the modules used by that in source form +1. Compile and start Terasology (see #Dev-Setup) +1. Select "CoreSampleGameplay" and click on "Advanced Game Setup" +1. Double-click on the module you grabbed to activate it +1. Start the game + + +## Get Help when Facing Issues + +* Check out our wiki pages on [Troubleshooting](Troubleshooting-Developer.md) +* Join our community on [Discord](https://discord.gg/terasology) and ask questions + + +## Start Contributing + +* Take the [Gooey Tour](https://terasology.org/AdventureSite/) to find resources for the contribution area you're interested in +* Look through the code, change small things and see how they affect your game +* Find some ["Good First Issues"](https://github.com/MovingBlocks/Terasology/labels/Good%20First%20Issue) to work on +* Code and test your changes locally in-game +* Push to your fork for engine changes, create module forks and push module changes there +* Make PRs and ask the community for review + +Check out the general [contributing guidelines](https://github.com/MovingBlocks/Terasology/blob/develop/.github/CONTRIBUTING.md). + + +## Go deeper + +You can read through the intro topics for more details on exactly how to set up and develop. + +* [Resources for Learning Git & GitHub](https://help.github.com/articles/good-resources-for-learning-git-and-github) + * [Recommended Git Tutorial](http://learngitbranching.js.org) + * [Recommended GitHub Tutorial](https://help.github.com/categories/bootcamp) +* [Codebase Structure](Codebase-Structure.md) +* [Module Dependencies](Module-Dependencies.md) - explains how you can have module `X` depend on module `Y` even at a specific version level +* [Developing Modules](Developing-Modules.md) - shows you how to interact with and organize modules that hold most the content for the game +* Advanced Gradle and Groovy usage: take a look at `gradlew tasks` and `groovyw usage` +* [Using Locally Developed Libraries](Using-Locally-Developed-Libraries.md) + + +## Notes + +0 If you feel more comfortable on other shell types, e.g. fish, zsh, powershell, etc. that's fine. [↩](#a0) + +1 For Windows users, we highly recommend Git for Windows which comes with both, a GUI client and shell integration for Git, and in addition brings the Git Bash which allows Windows users a unix-style command-line experience. [↩](#a1) + +2 We recommend IntelliJ, because we have a series of customizations that prepare run configurations, Git integration, and so on for the project. You can use any IDE (or none at all) that you like, however you will not be able to benefit from these customizations. [↩](#a2) + +3 To get all modules that are part of our release, grab the "omega" line-up instead. Please note, that this line-up requires more memory and time for compilation and start-up. Check our `Index` repo to see all available [line-ups](https://github.com/Terasology/Index/tree/master/distros). [↩](#a3) + +4 Please note, that both `gradlew` and `groovyw` are scripts locally present in your workspace root directory. On *nix systems, you can execute them from within the root directory by prefixing them with `./`. [↩](#a4) \ No newline at end of file diff --git a/docs/Dealing-with-Forks.md b/docs/Dealing-with-Forks.md new file mode 100644 index 00000000000..6a25d2aa7b7 --- /dev/null +++ b/docs/Dealing-with-Forks.md @@ -0,0 +1,67 @@ +Alright, you have gone through [Contributor Quick Start](Contributor-Quick-Start.md) and maybe looked at [Developing Modules](Developing-Modules.md) - now how about actually submitting some changes back to GitHub? + +There are two ways to submit changes back to GitHub, either gaining write ("push") access to any of our root repos or forking personal copies of any of them yourself. + +The examples below are fairly light and expect some minimal knowledge of Git or ability to surf Google to learn. You may also consider native clients like [GitHub Desktop](https://desktop.github.com) if available to you. + +There are plenty of [good Git tutorials on the web](http://learngitbranching.js.org) - this link goes to one of them. + + +## Creating a fork + +To get your own personal copy of a repo on GitHub you simply click the "Fork" button at the main page of any repo. You'll have full rights on the resulting fork. + +You can see how a root repo (in this case `MovingBlocks/Terasology`) and its forks relate by checking the network graph: https://github.com/MovingBlocks/Terasology/network + +Each dot is a unique commit containing a change, each label is a branch, and each section beyond `MovingBlocks` is somebody's personal fork of Terasology's main project repo that contains unique changes. + +If you made a commit in your fork of the Terasology repo it would show up as its own dot in your username's section. May have to refresh your browser once or twice if the change is recent :-) + + +## Getting direct write access + +While you can fork module repos we hand out write access to modules pretty easily. So long as you've made a good impression, proven yourself able to make changes with Git, and have an interest in working on a module not actively being worked by somebody else, you're in! + +Multiple people can work directly on a single module repo if they coordinate well, but this is where it becomes useful to work via Pull Requests (PRs - see below) + +To get access ask in our [forum](http://forum.terasology.org/forum) - be patient please :-) + +Trusted long-term contributors can eventually get these rights to the main repos under the `MovingBlocks` organization on GitHub. + + +## Updating a fork + +After you make a fork you need to create a second remote reference in your local Git root. There are better guides to Git elsewhere, but in short: + +* If you cloned `MovingBlocks/Terasology` then that will be your remote named `origin` but you won't (to begin with) have push rights to it. You add a second remote maybe named after your username, so our mascot would name it `gooey`, and push your changes there +* If you cloned your fork then that will be your `origin` remote and you can add a second remote to `MovingBlocks/Terasology` - this you could name `movingblocks` or `upstream` and use to pull updates when changes are made there. + +Naturally you can adjust that process for modules. The main difference there is that you first need to `cd modules/[name]` where `[name]` is the module to work with. This is so you're interacting with your nested Git root for the module rather than the Terasology root project. + +In the following diagram our mascot Gooey (GitHub username [GooeyHub](https://github.com/GooeyHub)) cloned `MovingBlocks/Terasology` first then made a remote named `gooey` to the fork using `git remote add gooey https://github.com/GooeyHub/Terasology` + + + +When you have two remotes defined (and use `git fetch --all` or Fetch under Git options in an IDE) you can now pull and push code between your local workspace and GitHub. A regular workflow then goes like (assume `origin` is your fork and `upstream` is `MovingBlocks/Terasology`): + +* Write some code +* Make a local commit in your develop branch + * If the change is at all substantial consider using a topic branch instead - see note below +* Push your local changes to your fork on GitHub: `git push origin develop` +* Make a PR (look below) +* Wait for it to be accepted, optionally submit more changes +* After the PR is merged and other changes have happened you update your local workspace with `git pull upstream develop` + +**Note:** While this is easy and straight forward the concept of [topic branches](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows) has become more popular over time and should ideally be used for each substantial change you make. Essentially you make a new branch per change, so you can switch back and forth as needed, keeping `develop` clean in case you want to test without your change or make more independent branches from it. This also lets you simply delete "spent" branches. + +## Creating a pull request (PR) + +When you have suitable changes to be submitted to somebody else's repo on GitHub from your fork you can issue a "Pull Request" to get their attention and review for your changes. + +At your repo page, for instance https://github.com/GooeyHub/Terasology, you should see a summary comparing your selected branch to the matching branch in the repo you forked from, listing outstanding differences if any. + +Simply click the "Pull Request" button to get started. Make sure your target (may be called "base fork") and source (may be called "head fork" - your fork) are correct and the changes are what you expect. + +In your description please describe the changes you've made and how to test them, along with any particular review notes / justification for why you made the change, if needed. Submit the PR then please wait for project staff to review your request - could take a little while :-) + +*Note:* While normally you would PR a change from one repo (like a fork) to another (like the root repo) nothing prevents you from using a PR inside a single repo to go from one branch to another. Some stay organized and review their code that way. \ No newline at end of file diff --git a/docs/Developing-Commands.md b/docs/Developing-Commands.md new file mode 100644 index 00000000000..68a8beb66b8 --- /dev/null +++ b/docs/Developing-Commands.md @@ -0,0 +1,94 @@ +This is an article for developers who want to use and create their own console commands (for example for mods). + +Adding new console commands to Terasology is easy. The steps below show what is needed for console commands. +Command implementation + +Command structure +============== + +Every command must be implemented as a public method of a ComponentSystem. E.g. the following command just displays "hello world" in the console. + +```java +@RegisterSystem +public class MyCommands extends BaseComponentSystem { + + @Command( shortDescription = "Say hello", helpText = "Writes hello world to the console" ) + public String hello() { + return "hello world"; + } +} +``` + +Looking at this simple examples we can see several important things: +* The command method must be located in a class implementing ``ComponentSystem`` +* The command annotation ``@Command`` is necessary for every command +* One can specify a short description and a (probably) longer help text +* A returned string will be shown in the console. + +Creating your own console commands +------------------ + +To specify a new console command, just an annotated public method is needed in a ComponentSystem. The annotation is +```java +@Command() +``` +and marks the method as a command. The command will have the same name as the method, +e.g. if you name you method ``public void hello()`` the command ``hello`` will be available in the game. + +Short Descriptions and Help Text +----------------- +Short descriptions and help texts can be added via the method annotation. To specify a short description, just add +```java +shortDescription = "text for short description" +``` +to the annotation, e.g. +```java +@Command( shortDescription = "some command description" ) +``` + +Probably longer help text can be specified via ``helpText`` in the annotaion. An example is given below: +```java +@Command( helpText = "A command without short description, but with a longer help text." ) +``` + + +Displaying text +------------------ +Any value returned from the command (string or object) will be displayed in the in game console. + +You can also write directly to the console via the Console class. + +Parameters +------------------- +Of course it is possible to give parameters/arguments to your command when executed in the command line. These +arguments are specified as method arguments. It is highly recommended to prefix the method arguments by a parameter +annotation, that is used for the command line help. +```java +@Command( shortDescription = "Echo-cho-cho-o-o", helpText = "Echoes the input text." ) +public String echo(@CommandParam( value = "Message" ) String message) { + return message; +} +``` +The method above will add an ``echo `` command that simply echoes the input text. The command is proper annotated, +resulting in user friendly help messages and command description. + +The supported types for command parameters are: float, int, String. + +Commands and Multiplayer +------------------- + +By default, commands run locally - on the client side. +A command can be marked as runOnServer, in which case it will be replicated to the server in a multiplayer game and executed there: + +```java +@Command(runOnServer = true) +``` + +In such a case, the command method can have a final EntityRef parameter. This will be populated with the Client entity of the calling player. + +```java +@Command(shortDescription = "Sends a message to all other players", runOnServer = true) +public void say(@CommandParam("message") String message, EntityRef speaker) { + // ... +} +``` \ No newline at end of file diff --git a/docs/Developing-Modules.md b/docs/Developing-Modules.md new file mode 100644 index 00000000000..535e68df9a3 --- /dev/null +++ b/docs/Developing-Modules.md @@ -0,0 +1,122 @@ +To work with modules you need to either fetch existing ones or create new ones. We have utility tasks in Groovy to make this process easier. + +When working on modules there are two things that you can do + +1. [Contribute to an existing Module](#contributing-to-existing-module) +2. [Create a new Module](#create-a-new-module) + +## Contributing to existing module + +Let us use the `Sample` module from https://github.com/Terasology/Sample for the examples below. In the root of your workspace execute: + +`groovyw module get Sample` + +(in a Linux(-like) terminal you'll need to use `./groovyw`) + +Where `Sample` is the name of the module you want to contribute to. In the case of the `Sample` module Groovy will fetch the existing GitHub repo from https://github.com/Terasology/Sample and place it in your local workspace at `modules/Sample` + +To properly adjust your workspace you need to let Gradle refresh, by clicking the little refresh icon in the Gradle tab of IntelliJ + +After the refresh process finishes IntelliJ should notice the new module(s) - may take a moment or two + +You may notice that additional files and directories were created in the `Sample` directory. This includes the `build.gradle` needed to build the module, along with placeholder folders for all asset types and such. + +### To add a new feature or fix a bug + +Follow these steps: + +- Create a fork of the module repo, or gain access to make branches in the module under the Terasology org +- Make sure your local workspace is up-to-date with the main repository by running `groovyw module update Sample` (or whichever module(s)) +- Create a new branch to work on the new feature or bug via the updated branch `git checkout -b "branch_name"` +- Work on the feature/bug and stage all the files to commit it on that branch `git add .` > `git commit -m "Commit Message"` +- Push the branch to your fork `git push -u origin branch_name` +- Create a pull request. + +For detailed explanation on dealing with forks checkout the [See also](#see-also) section + +## Create a new module + +For new modules there is an additional step or two. Start with a slightly different command: + +`groovyw module create MySample` + +This will create a module named "MySample" at `modules/MySample` + +As with fetching a module be sure to let Gradle refresh your workspace after your module lineup has changed. + +You'll notice the new module directory has been created with some placeholder files. Adjust [module.txt](Module.txt.md) accordingly to describe your module. + +To work on your new module make sure that - + +- Your local workspace is up-to-date with the main Terasology repository (even if you're working on a module). +- Create a new branch to work on the new feature or bug via the updated master branch `git checkout -b "branch_name"` +- Work on feature/bug and stage all the files to commit it on that branch `git add .` > `git commit -m "Commit Message"` +- Push the branch to your fork `git push -u origin branch_name` +- Create a pull request. + +If you're working on a new gameplay template (as opposed to utility modules meant to be enabled alongside a different template) you'll need to add CoreRendering as a dependency, which can be done in the [module.txt](Module.txt.md) like this: + +```json +{ + "id" : "MySample", + "version" : "0.1.0-SNAPSHOT", + "author" : "", + "displayName" : "MySample", + "description" : "", + "dependencies" : [ { "id": "CoreRendering", "minVersion": "1.0.0" } ], + "serverSideOnly" : false +} +``` + +Connecting your new module to a home on GitHub can be done in one of two ways, either of which needs you to create a new remote reference in the local Git repo. + +* You can kindly ask project staff to create a module repo for you under the [Terasology organization on GitHub](https://github.com/Terasology) and give you access. +* You can create your own module repo on your personal GitHub account + +After you have a module repo on Github, `cd` to `modules/MySample` and execute `git remote add origin https://github.com/[username]/MySample` + +Where `[username]` is either your account name on GitHub for a personal repo or `Terasology` for official module repos. Fetch from and push to your new module home on GitHub and make some PRs! + + +## Understanding Terasology's Git setup + +Having fetched or created a module you now have *two* Git repos in your local workspace. + +* The root Terasology project containing the engine and everything else +* The module with its own nested Git root under `/modules/Sample` or so + +This is known as having a nested Git project in your workspace. The nested Git root (the module) is excluded from tracking in the Git repo holding the main Terasology stuff. + +All that means is that you treat the two pieces independently when it comes to source control. IntelliJ and other tools can handle this very easily. Here is a diagram to explain: + + + +For more information, go to [Multi-Repo Workspace](Multi-Repo-Workspace.md). + +## Structure of modules + +This is just a sample listing of assets - there are more types. See our [asset tutorial](https://github.com/Terasology/TutorialAssetSystem/wiki) for more + +* `/assets` - place resources related to the module under here and our Asset System will find them. You can optionally introduce additional directory levels under each asset type to organize better (subdirs are ignored by the game engine, just a human convenience) + * `/blocks` - block definitions go here, which are simple JSON files holding any special instructions related to each block (or nothing at all). Each block may reference one or more textures for its faces. See [Block System](Block-Definitions.md) for more details + * `/blockTiles` - block textures go here and are usually matched by block definition files. However, if you place an `auto` directory under here any images there will automagically become basic blocks (same texture on all sides, no special traits) + * `/prefabs` - these JSON files describe entity recipes that can be used by the game engine to create objects in-game. This could for instance be a Portal describing what it is able to spawn, or a chest block able to hold items. See [Entity system concepts](Entity-System-Architecture.md) + * `/sounds` - another asset type example. You can place an audio file here in the OGG format and then reference it using the mod's namespace, such as `portals:spawn` +* `/src` - actual source code for custom functionality goes under here. Usually this will be custom Components and Systems that make up the core content in our [Entity System Architecture](Entity-System-Architecture.md) + * `/ui` - ui-related classes such as HUD widgets or screens (see our [Nui Tutorial](https://github.com/Terasology/TutorialNui/wiki)) + * `/world` - world-related classes, for instance facets, providers, and rasterizers (see our [World Generation Tutorial](https://github.com/Terasology/TutorialWorldGeneration/wiki)) + * `/topicA` - place components, events, and systems related to a specific topic into the same sub-package - this allows for the classes to access each other's package-private members and methods + * `/topicB` - try to cluster components, events, and systems based on the "thing" or "action" they represent, notify about, or manage + +## Namespace + +The typical namespace for a module is `org.terasology.module. `. It is recommended to name the source packages accordingly, otherwise the modules may not be built or loaded as expected. + +_See [#2445](https://github.com/MovingBlocks/Terasology/issues/2445) for more details._ + +## See also + +* [Modding API](Modding-API.md) - the methods a module is allowed to call +* [Testing Modules](Testing-Modules.md) - test your module with unit tests and integration tests +* [Module Dependencies](Module-Dependencies.md) - how to deal with modules that depend on another +* [Dealing with Forks](Dealing-with-Forks.md) - work with your own copies of GitHub repos you can write to diff --git a/docs/DevelopingModules.png b/docs/DevelopingModules.png new file mode 100644 index 00000000000..c39e8b3ed25 Binary files /dev/null and b/docs/DevelopingModules.png differ diff --git a/docs/Discord-Integrations.md b/docs/Discord-Integrations.md new file mode 100644 index 00000000000..1700201e8ea --- /dev/null +++ b/docs/Discord-Integrations.md @@ -0,0 +1,30 @@ +## How it works + +* webhook is configured on Discord server +* GitHub repo is configured to push html post updates to Discord webhook +* Discord webhook receives data and posts it as a message to the selected channel + +  + +## How to set up / update Discord webhook + +1. Go to `Server Settings` +1. In the settings, go to `Integrations` +1. Select `Show Webhooks` +1. Create new webhook or edit existing one + +  +1. Copy the webhook URL + +## How to set up / update GitHub webhook integration + +1. Go to the desired repo's `Settings` +1. In the settings, go to `Webhooks` +1. Create new webhook integration or edit existing one + +  +1. Insert the webhook URL copied from the Discord settings into the "Payload URL" field +1. In the "Payload URL" field, append `/github` to the webhook URL +1. Ensure "Content type" field is set to `application/json` + +_Note:_ Consider selecting individual events to avoid spamming the target channel on Discord with irrelevant messages. diff --git a/docs/Documentation-Guide.md b/docs/Documentation-Guide.md new file mode 100644 index 00000000000..c3f814e25a2 --- /dev/null +++ b/docs/Documentation-Guide.md @@ -0,0 +1,68 @@ +Documentation is a crucial part of making and keeping software understandable and maintainable. +Especially in open source development where the contributor basis is subject to frequent fluctuation, it's important to provide maintainers with sufficient information about intentions, assumptions, issues and future plans when writing code. + +The following guidelines will explain the various levels of detail documentation can be created with and the associated purposes and characteristics of said documentation. + +## Level of Detail 0 - Code + +Code can serve as documentation of the logic it represents. Proper documentation requires understandable and unambiguous variable and function names, clear order of instructions, etc. + +This form of documentation should be very low-level and specific to the implemented logic. It's easy to maintain as it's bound to change anyway when the logic itself changes. Both change authors and reviewers are responsible to verify the naming and structure used in new or improved code are comprehensible. + +- used for debugging or in-depth understanding of the code-base +- can seem superfluous or obvious to contributors familiar with the topic or part of the codebase +- can be repetitive which might be annoying when learning about the code-base but is crucial when hunting down bugs + +### Example + +```java + @ReceiveEvent(priority = EventPriority.PRIORITY_TRIVIAL) + public void changeMaxHealth(ChangeMaxHealthEvent event, EntityRef player, HealthComponent health) { + int oldMaxHealth = health.maxHealth; + health.maxHealth = (int) event.getResultValue(); + Prefab maxHealthReductionDamagePrefab = prefabManager.getPrefab("Health:maxHealthReductionDamage"); + player.send(new DoDamageEvent(Math.max(health.currentHealth - health.maxHealth, 0), + maxHealthReductionDamagePrefab)); + player.send(new MaxHealthChangedEvent(oldMaxHealth, health.maxHealth)); + player.saveComponent(health); + } +``` + +## Level of Detail 1 - JavaDoc & Code Comments +- updating should be part of PR, both author's and reviewers responsibility +- less specific, but still rather detailed on what's happening +- similar to a short summary of what a class, function, or section of code (pack of lines) does +- used for debugging and learning how and for what to utilize classes and functions +- can also be used to find action items for contributions, for instance future plans for features or refactorings to improve the code-base + +### Example + +```java + /** + * Sends out an immutable notification event when maxHealth of a character is changed. + */ +``` + +## Level of Detail 2 - Module Documentation + +- /docs folder +- describe scope of systems, triggers for events, what components represent +- updating should be part of PR +- used for learning how and for what purpose to use a module +- should link to module API (JavaDoc) for a more in-depth and technical perspective + +### Example + +> The Health Authority System handles changes of player health, but doesn't manage occurrences of damage. Changes in player health can originate from various sources, including damage, impairment effects, gameplay events, etc. None of these is relevant for the Health Authority System, it only cares about the actual change of the player health value and the associated events used to change it. + +## Level of Detail 3 - Engine Wiki / Tutorial Modules +- hard to maintain as not part of the version control +- conceptual, generalized +- used to learn how a project is setup and works on a coarse-grained point of view +- provides means for conceptual or learning-by-doing learning types +- topics: patterns, tools, architecture +- should ideally make use of diagrams and examples to also enable visual learning types + +### Example + +For instance, this page. \ No newline at end of file diff --git a/docs/Eclipse.md b/docs/Eclipse.md new file mode 100644 index 00000000000..13440616196 --- /dev/null +++ b/docs/Eclipse.md @@ -0,0 +1,27 @@ +Eclipse can be used with Terasology just like IntelliJ, but needs a little more manual setup. + +TODO: We have a few more files at `config/eclipse` that could use some setup instructions and/or automated customization like for IntelliJ. + +### Note + +All of the settings described below can be applied to a specific Eclipse project or to an entire workspace. + +- To apply the settings on a per-project basis, right-click on a project in the Package Explorer and select _Properties_. (Alternatively, select the project and press Alt+Enter.) After navigating to a relevant section of the Preferences menu, check _Enable project-specific settings_. Repeat this for all the projects you'd like to work on. + +- To apply the settings globally, select _Window → Preferences_ from the main menu and navigate to a relevant section. + +### Formatting Convention Setup + +- In _Java Code Style → Formatter_, click _Import_ and import Terasology's formatting settings file ([Terasology/config/eclipse/formatting.xml](https://github.com/MovingBlocks/Terasology/blob/develop/config/eclipse/formatting.xml)). The _Terasology formatting conventions_ profile should be automatically selected. + + + +### Import Order Setup + +- In _Java Code Style → Organize Imports_, click Import and import Terasology's import order file ([Terasology/config/eclipse/.importorder](https://github.com/MovingBlocks/Terasology/blob/develop/config/eclipse/.importorder)). + + + +- **[Optional, but recommended]** Switch to _Window → Preferences → Editor → Save Actions_. Check _Perform the selected actions on save_ and _Organize imports_. + + \ No newline at end of file diff --git a/docs/EclipseFormatterSettings.png b/docs/EclipseFormatterSettings.png new file mode 100644 index 00000000000..bd3a9b8555d Binary files /dev/null and b/docs/EclipseFormatterSettings.png differ diff --git a/docs/EclipseImports1.png b/docs/EclipseImports1.png new file mode 100644 index 00000000000..0b4e8c1d3b5 Binary files /dev/null and b/docs/EclipseImports1.png differ diff --git a/docs/EclipseImports2.png b/docs/EclipseImports2.png new file mode 100644 index 00000000000..224d2f29726 Binary files /dev/null and b/docs/EclipseImports2.png differ diff --git a/docs/Entities-Components-and-Events-on-the-Network.md b/docs/Entities-Components-and-Events-on-the-Network.md new file mode 100644 index 00000000000..598eb1f8436 --- /dev/null +++ b/docs/Entities-Components-and-Events-on-the-Network.md @@ -0,0 +1,111 @@ +Unlike in single player, the client and the server reside on different instances in multiplayer. Therefore, components and entities have to be correctly configured to ensure that they work as intended in a multiplayer setting. Often, this means annotating the relevant fields with `@Replicate`. + +`@Replicate` is an annotation used to mark types or fields to indicate that these types or fields should be replicated between the server and the client. In other words, when changes are made to these types or fields on the server, these changes will be reflected in the clients as well. + +This page will focus on component fields and how they can be replicated by the network. However, take note that `@Replicate` can be applied on component classes as well. This is especially important for ensuring that empty components are correctly replicated. Currently the Replicate annotation on the component does not get used as default for the fields. So fields need to be marked for replication if you want them to be replicated. + +To illustrate how `@Replicate` can be used, let's take a look at a field in `ItemComponent`: + +```java +/** +* How many of said item are there in this stack +*/ +@Replicate(FieldReplicateType.SERVER_TO_CLIENT) +public byte stackCount = 1; +``` + +The `stackCount` field in `ItemComponent` specifies the amount of items in the current stack. + +As you can see, under the `@Replicate` annotation, the `FieldReplicateType` element is set to **SERVER_TO_CLIENT**. This annotation ensures that this when the value of the `stackCount` field of `ItemComponent` is updated on the server (i.e. when the stack size of the item changes), its value on all connected clients will be updated as well. Obviously very important as the number of items in a stack should be always be updated on all clients! + +Apart from **SERVER_TO_CLIENT**, there are also a few other values for `FieldReplicateType` that determine the circumstances under which the field will be replicated. + + `FieldReplicateType` | Description +--------|------------- +**SERVER_TO_CLIENT** | The field will be replicated by the server to all clients connected to the server. This is the default `FieldReplicateType`. +**SERVER_TO_OWNER** | The field will be replicated by the server to the client only if the client is the owner (i.e. the client belongs to the entity containing the component). +**OWNER_TO_SERVER** | Functionally the same as **OWNER_TO_SERVER_TO_CLIENT** +**OWNER_TO_SERVER_TO_CLIENT** | The field will be replicated from the owner to the server. It will be then be replicated by the server to all connected clients that are not the owner. + +Apart from `FieldReplicateType`, you can also specify the value of the `initialOnly` element, which is false by default. When set to true, the field will only be replicated once when the entity containing the component first becomes relevant to the client. + +For instance in `ItemComponent`, it is used in `maxStackSize`: +```java +@Replicate(value = FieldReplicateType.SERVER_TO_CLIENT, initialOnly = true) +public byte maxStackSize = 99; +``` + +Unlike `stackSize`, which might change over the course of a game as the player receives or uses the item, the `maxStackSize` of an item does not change. Therefore, the `initialOnly` element is set to true as the value of `maxStackSize` only needs to be replicated by the server to the client once when the `ItemComponent` first becomes relevant. + +To summarise, the server will send replicated fields only when: + +1. It is the initial send of the component field +2. The field is replicated from Server to Client +3. The field is replicated from Server to Owner and the client owns the entity +4. The field is replicated from owner and the client doesn't own the entity + +The exception to this is when `initialOnly` is set to true and it isn't the inital send of the component field. + +**Take note**: There is also the `@NoReplicate` annotation, which is the opposite of `@Replicate` annotation. It specifies that a component field should **not** be replicated. By default, all fields except Event fields are not replicated. + +**Take note**: Don't forget to use `entityRef.saveComponent(component)` to save change of value in the component, or the change will not replicate. + +## NetworkComponent + +However, for updates to component fields of an entity to be replicated in a server, the entity needs to be registered on the network, which is where `NetworkComponent` comes into the picture. + +When `NetworkSystem` is first initialised, all entities containing a `NetworkComponent` are registered on the network as network entities and given a network ID. While entities might have different IDs each time, network entities are linked to their respective entities through the network IDs, allowing these entities to survive dropping in and out of relevance. + +Similar to `FieldReplicateType`, the `ReplicateMode` enum determines which clients the entity should be replicated to (i.e. which clients the entity is registered on). + + `ReplicateMode` | Description +--------|------------- +**ALWAYS** | The entity will always replicated to all clients connected to the server. +**RELEVANT** | The entity will only be replicated to clients where it was relevant (within a certain distance). This is the default value. +**OWNER** | The entity will always be replicated to its owner. + +An example whereby both the `@Replicate` annotation and `NetworkComponent` are used is in the chest. + +Chests store their items in `InventoryComponent`, in the following List: +```java +@Replicate +@Owns +public List itemSlots = Lists.newArrayList(); +``` + +Again, the `@Replicate` annotation ensures that whenever the value of the component field is updated on the server, this change will be reflected in all clients as well (recall that the default value of `FieldReplicateType` is **SERVER_TO_CLIENT**). In other words, whenever a player modifies the items in the chest, others in the same server will be able to see this change. + +However, if the chest entity is not registered on the network, not all clients connected to the server might recognise the chest entity, preventing them from interacting with it. This is why `NetworkComponent` is specified in `chest.prefab` as well: + +```javascript +... +"Network": { +} +... +``` + +Recall that the default `ReplicateMode` is **RELEVANT**. This `NetworkComponent` thus ensures that the chest entity will always be replicated by the server to a client whenever it is relevant to the client, ensuring that all interactions with the chest work as intended. + +## @ServerEvent + +As mentioned previously, event fields are all replicated by default. + +However, for events that are consumed by the server, they have to be marked with the `@ServerEvent` annotation. When events marked with `@ServerEvent` are sent on the client, they will be replicated to the server as well so that they can be actioned there. + +This is very important for events that require action on the part of the server, such as `AbstractMoveItemRequest` and `DropItemRequest`. + +```java +@ServerEvent +public abstract class AbstractMoveItemRequest implements Event { +... +``` + +```java +@ServerEvent(lagCompensate = true) +public class DropItemRequest implements Event { +... +``` + +You can also specify the `lagCompensate` element when marking events with the `@ServerEvent` annotation, as seen from `DropItemEvent` It is false by default. If set to true however, the positioning of all characters on the server will be rewound to simulate the conditions on the client when the event was initially sent before the event is processed by the server. + +In the case of `DropItemRequest`, there is a need for `lagCompensate` to be set to true as the item should be dropped at the position where the character was when the request was initially sent, rather than the position where the character is when the event is received by the server. This thus takes into account the time taken for the request to be sent from the client to the server. \ No newline at end of file diff --git a/docs/Entity-System-Architecture.md b/docs/Entity-System-Architecture.md new file mode 100644 index 00000000000..788f349076e --- /dev/null +++ b/docs/Entity-System-Architecture.md @@ -0,0 +1,247 @@ +The **Entity Component System Architecture** (ECS) is built upon three pillars: entities, components, and systems. +We are going to give a brief overview of what those are, and how they work together in a game (engine) like Terasology. + +- [Entities](#entities) + - [EntityRef](#entityref) + - [Prefabs](#prefabs) +- [Components](#components) + - [Component Data Types](#component-data-types) + - [Component Library](#component-library) + - [Modifying Components](#modifying-components) +- [Systems](#systems) +- [Events](#events) + - [Events in Detail](#events-in-detail) +- [Example modules](#example-modules) +- [Further Reading](#further-reading) + +## Entities + +At the core of the Entity System we have entities - these are identifiable "things" in the world. +However an Entity by itself doesn't do anything - it has no data, nor behavior. +It is merely a logical container for one or more [Components](#components) - these provide data, and behavior through their interaction with [Systems](#systems). + +For instance, the player is an entity, a single enemy is an entity, a chest is also an entity. +Entities don't have to be objects that are visible in the world either - they can be scoreboards, loot tables, a UI, and other gameplay related things. + +### EntityRef + +In Terasology, entities are worked with through the _EntityRef_ class. +For the most part this just delegates requests to the _Entity Manager_ - the central manager for the Entity System. +The EntityRef itself does not store components, these are stored in the Entity Manager within a hashed table, to allow ease of iterating over all entities with a given type of component. + +EntityRef uses the [Null Object Pattern](https://en.wikipedia.org/wiki/Null_object_pattern) - instead of using Java's null, `EntityRef.NULL` should be used. +`EntityRef.NULL` can be safely accessed with all its functions providing sensible default results - this removes the need to check whether an EntityRef is null in many cases. +Where it is needed, the `exists()` method can be called to check whether an EntityRef is a valid reference. + +One particular feature of the EntityRef is that when an entity is deleted, all references to it are invalidated and act like `EntityRef.NULL` from then on. +This allows EntityRef to be safely used in components, and Entity ids to be reused. + +### Prefabs + +> 🚧 TODO: move this to sub-page or tutorial module + +A prefab is a recipe for creating entities (a "pre-fabricated entity"). +Prefabs mimic an actual entity - they have components with all the usual values - but are not processes by systems. +Instead, they can be used to create an entity with the same components and the same settings. + +In Terasology, prefabs can be defined in a JSON format and included in modules. +A prefab file is a set of components with their respective parameters and values described in a JSON structure. + +```json +{ + "name": "core:gelatinousCube", + "Location": {}, + "Mesh": { + "renderType": "GelatinousCube" + }, + "CharacterMovement": { + "faceMovementDirection": true + }, + "SimpleAI": {}, + "AABBCollision": { + "extents": [0.5, 0.5, 0.5] + }, + "CharacterSound": { + "footstepSounds": [ + "engine:Slime1", + "engine:Slime2", + "engine:Slime3", + "engine:Slime4", + "engine:Slime5" + ], + "footstepVolume": 0.7 + } +} +``` + +The prefab has a name that identifies it (this name will be derived from its file name in a module), and a number of components (referred to by the name of the component class with "Component" dropped from the end if present). +Within each component the default values for each property can be overridden. + +Additionally, prefabs can be used as a read-only source of information, without ever making entities from them. +They could be used to describe crafting recipes for instance. + +Prefabs can also be inherited within the same module, or from other modules. +This will inherit all of the parent components and settings and then add any additional components or change any different settings. + +```json +{ + "name": "core:angryGelatinousCube", + "parent": "core:gelatinousCube", + "CharacterMovement": { + "speedMultiplier": 0.3 + } +} +``` + +A few thumb rules for prefab inheritance are: + +- When a prefab inherits another, all of the parent components are inherited as well. It is enough to create a `.prefab` file containing only the tag `{ "parent": " "}` +- Duplicated components are overwritten: if the parent contains the same component as the child but with different values, the child's component description will prevail/overwrite the original. Similarly, components cannot be removed in the child's prefab: if a component is described in the parent prefab but not in the child, the entity created from the child prefab will contain the missing module as described in the parent prefab. +- Components can only be described and inherited in full. If a component described in the parent prefab possess more than one parameter but it is only necessary to change one of the values, all other parameters and values must be repeated in the child prefab. + +Prefabs can then be instantiated at runtime through the EntityManager. + +Usage of prefabs provides a number of benefits. +Prefabs reduce the size of save data and network data - rather than using the full set of data for an entity, just the prefab the entity uses and delta of differences can be used. +Prefabs also allow existing objects to be updated - when you change a prefab and load a level, any changes to the prefab will be reflected in any instances in that level. +There is also potential to use prefabs as static data - for instance they could be used to describe crafting recipes or materials without ever creating an entity. + +Prefabs are still an area for future development - at the moment they have a number of limitations: + +- You cannot specify nested entities that should be created and related to a EntityRef property when a prefab is instantiated (like the items in a player's starting inventory). +- A child prefab cannot remove an entity defined by a parent prefab. + +## Components + +A component is a meaningful set of data, with a intention of being used to provide behavior, that can be attached to an [Entity](#entities). +For instance, a Location component stores data relating to an entity's position in the world - with the implication that the entity is something in the world. +A Mesh component holds information about a mesh used to render the entity - but its presence along with a LocationComponent also implies the entity should be rendered. + +Typically a component is a plain java object with a flat set of value objects and minimal functionality. +There may be some data related methods (to ensure values are not set to null, for instance), but there should not be any game logic - that should be provided by the [Systems](#systems). +Components may contain EntityRefs, but should never have a reference to other Components, or to Systems. + +Components should be declared final. + +> Each entity can have at most one Component of a given type - an entity may have a Location, but cannot have multiple locations. +> Generally if you come across a situation where having multiple of the same component may seem attractive, you would be better served by using multiple entities with a component to tie them to a "main" entity. + +Components may only contain specific data types - this is used to support persistence. + +This structure provides flexibility and reuse when creating entities - you can add any of the existing components to make use of their features, and concentrate on creating new components for any features that don't presently exist - if any. + +### Component Data Types + +- Standard Java Primitives - double / float / int / boolean / long and their equivalent boxed types +- String +- Enums +- Map<String,X>, where X is one of the supported types. The generic must be specified. +- List<X>, where X is one of the supported types. The generic must be specified. +- Set<X>, where X is one of the supported types. The generic must be specified. +- EntityRef +- BlockFamily +- Color4f +- Vector2f / Vector3f / Vector2i +- Quat4f +- Texture +- and simple POJOs composed of above (marked with the @MappedContainer annotation) + +This list can be extended - see [Component Library](#component-library) section below. + +### Component Library + +The ComponentLibrary stores information about the components, which is used to handle persistence. When a component is registered with the ComponentLibrary, all of the properties of the component are enumerated, and a ComponentMetadata object is created with a list of those properties, their types, and methods to get and set that field in an object. + +### Modifying Components + +In general usage you use EntityRef's `addComponent` method to attach a component to an entity, and `removeComponent` to remove it. +`getComponent` can be used to retrieve a component for inspection or modification. +At the moment, after modifying a component `saveComponent` should be used to save it back to the EntityRef - this causes an event to be sent. +Future implementations may require this call for the component changes to actually occur though. + +There are additional methods following a functional programming approach to update and "upsert" an (existing) component via `updateComponent` or `upsertComponent`, respectively. + +## Systems + +Systems provide behavior to entities. They do this in two ways + +- Processing entities with a desired set of components in response to engine method calls like `initialise()`, `update(float delta)` and `render()` +- Responding to entity events sent to entities with a desired set of components + +For example, a particle system would iterate over all entities with both a Location and a Particle component (need the location to give the effect a position in the world, and the particle component is needed for the entity to be a particle effect in the first place) in each `update(float delta)` call, to update the particle positions. +The health system would respond to an entity with a Health component receiving a Damage event, in order to reduce an entity's health - and if the health reaches 0, send a Death event to the entity. + +A System provides the actual logic behind a component or combination of components - it can process them each frame, or respond to events dealing with them. Multiple components being involved is common - rendering a mesh from a Mesh component cannot be done without a location from a Location component, for instance. + +There are a number of advantages to the separation between data (in the Components) and logic (in the Systems) + +- **Allows modules to modify the behaviour of components.** + If a modder doesn't like the default behaviour of the Health component, they can replace the Health system with their own version - that will still work with all the existing entities with a Health component. +- **Allows optimization of the processing of multiple entities.** + +This triple system of [Entities](#entities) composed of [Components](#components) with [Systems](#systems) applying behavior provides a great deal of flexibility and extendability. +Often new behavior can be introduced through new components and systems. +Behavior can be completely changed by removing a system and putting a different one in its place. +And new entities can be created by mix and matching existing components and changing their settings, without even writing code. + +## Events + +Terasology also includes an event system built around the entity system. +Events are a mechanism used to allow systems to interact with each other. +Events are typed, and carry data - for instance, there is a DamageEvent that holds an amount of damage being caused, and the instigator responsible for the damage. +Events are sent to entities. +Systems can then provide event handlers to pick up specific events that have been sent entities with a desired set of components. + +For instance, when an entity is hit by a sword a DamageEvent is sent to it. +This event includes the amount of damage dealt - it could also include information on the type of damage, the source of the damage and so forth. +The Health System would subscribe to the damage event but only for entities with a Health component. +So if the hit entity has a health component then the health system would receive the event and can react to it by subtracting health - potentially sending another event if the entity's health reaches zero. +Another System could handle the same damage events for entities with a location and physics component, to knock the entity away from the damage causer. + +The advantage of using events rather than straight method calls between systems is that it decouples systems and provides the ability to add new systems in the future to react to the same event. +By sending a damage event rather than modifying the health component directly, it allows for systems that modify the damage being dealt based on arbitrary conditions, or cancel it, or display some sort of effect, or for the damage to be handled in a different way entirely without having to change the damage causer at all. + +This provides two valuable features: + +1. **react on events** It provides a mechanism for an entity to react to an event based on the components it has. + This means that someone can later on create their own component and system combination that reacts to Damage events differently. +2. **intercept and modify events** Because an event can be received by multiple systems, it is possible for modders to intercept and modify or cancel an event to change behavior. + An armor component could be added that halves all damage, and set up to intercept the damage event - without having to change the health system at all. + +### Events in Detail + +> 🚧 TODO: move this to sub-page or tutorial module + +New events should extend AbstractEvent, which provides the event with the default cancellation functionality. + +Systems that handle events should implement the EventHandler interface. They can then add new event handling methods by adding methods of the form: + +```java +@ReceiveEvent(components = {HealthComponent.class, AnotherComponent.class}, priority = ReceiveEvent.PRIORITY_NORMAL) +public void onDamage(DamageEvent event, EntityRef entity) { + // Do something +} +``` + +The method must have the signature `public void (T, EntityRef)`, where T is an type of Event - this determines which event will be sent to the method. The second parameter is the EntityRef for the entity that received the event. The name of the method and parameters can be anything, though I suggest starting the method name with "on", as in "onDamage". The method must also be annotated with @ReceiveEvent. The annotation must list what components an entity must have for the event handler method to be invoked - this allows you to filter out entities which are inappropriate for the event handler. You optionally may specify a priority, either using one of the preset priority levels or with an integer - this determines the order in which event handlers functions will be called when multiple are valid for a given event. + +Events also support cancellation - this allows a system to stop an event before it reaches systems with a lower priority - for instance if you add an invincibility component to make an entity temporarily immune to damage, you can add a system that will intercept the Damage event and cancel it before it can reach the health system. + +Inheritance structures of events are also supported - if you have a MouseButtonEvent, and a LeftMouseButtonEvent that inherits it, subscribing to MouseButtonEvent will also pick up LeftMouseButtonEvents. + +## Example modules + +Terasology's codebase can be daunting for somebody new to the project. Here are some examples that can hopefully provide some guidance for those who'd like to see how systems and components work in practice, starting from simpler modules and progressing to more complex ones. + +1. **[Hunger](https://github.com/Terasology/Hunger)** (basic complexity) - simple component, single widget UI, simple event handling. +1. **[Journal](https://github.com/Terasology/Journal)** (intermediate) - simple component, composite widgets in UI, key binding, introduces events sent over network. +1. **[GrowingFlora](https://github.com/Terasology/GrowingFlora)** (advanced) - advanced components, interaction with world generation and use of scheduled events, introduces concept of chunk states, I'd suggest not looking too much into the tree shape and growth generation itself (implementation) just look at the interfaces. +1. **[Workstation](https://github.com/Terasology/Workstation)** (advanced) - use of components for defining flow, use of prefabs for defining new types of objects, complex interaction with inventory, both player and entity. +1. **[BlockNetwork](https://github.com/Terasology/BlockNetwork)** and **[Signalling](https://github.com/Terasology/Signalling)** (fairly complex) - maintains a separate data structure for loaded entities to improve performance, listens on Component, Entity and Chunk life-cycle events to keep the data structure up-to-date, complex logic, delay handling of events. + +## Further Reading + +- [Block Entity Behavior](http://forum.terasology.org/threads/block-entity-behavior.792) +- http://www.richardlord.net/blog/what-is-an-entity-framework +- http://www.richardlord.net/blog/why-use-an-entity-framework +- http://t-machine.org/index.php/2007/09/03/entity-systems-are-the-future-of-mmog-development-part-1/ diff --git a/docs/Event-Types.md b/docs/Event-Types.md new file mode 100644 index 00000000000..1506c4e1117 --- /dev/null +++ b/docs/Event-Types.md @@ -0,0 +1,209 @@ +Events are signals which are send by systems against entities for communication and collaboration. + +Events extend the entity component system (ECS) by explicit means of communication. +You can find events everywhere in the code base - they notify about completed tasks, cause sounds to be played, and allow for decoupled extension and modification of behavior. + +> 💡 Keep in mind that events are processed synchronously, i.e., within the same tick of the game loop. + +We can categorize events by their _intent_ on sender side (similar to design patterns). + +- [Trigger Events](#trigger-events) +- [Notification Events](#notification-events) +- [Collector Events](#collector-events) + +## Trigger Events + +> Yo, please do this thing for me! + +The intent of a _trigger event_ is to make another system perform a specific action. +You can see this event as a command or request. + +An advantage of using trigger events is the reuse of functionality while maintaining only a loose coupling between modules. +A trigger event is a well-defined entry point for a process other systems can rely on. +Therefore, a module or system should describe its trigger events in its contract. +The sender is usually aware of (at least one) action that will be performed based on the event. + +> ⚠️ Keep in mind that a sending a trigger event does not guarantee the execution of an action. + +Examples for trigger events are inflicting damage to an entity (`DoDamageEvent`) or playing a specific sound asset (`PlaySoundEvent`). + +**Trigger events are _immutable_.** +The content of the trigger event is fully defined by the sending system. +No other system can alter the content. +This ensures that, if the event reaches the system it is logically addressed to, it was not tampered with. + +**Trigger events can be _consumable_.** +If a trigger event is consumable the command itself can be canceled before it reaches the target system. +Vice versa, if the event is _not consumable_ it is guaranteed to reach the target system. +If the [event flow] of an action offers a [Collector Event](#collector-events) the trigger should **not** be consumable. + +A simplified version of the mentioned `DoDamageEvent` may look like this. +The event is immutable and not consumable. + +```java +public class DoDamageEvent implements Event { + // private member, cannot be modified after event creation + private final float amount; + + public DoDamageEvent(float amount) { + this.amount = amount; + } + + public float getAmount() { + return amount; + } +} +``` + +When sending an instance of this trigger event to an entity, we want to express the intent of inflicting `amount` points of damage on an entity `entity`. + +```java +entity.send(new DoDamageEvent(amount)); +``` + +> 💡 The receiver system might specify additional requirements. +> For instance, damage might only be inflicted if the affected entity has a health component. +> These details should be stated in the module/system contract. + +Trigger events are often named in active form, e.g., `CloseDoorEvent` or `PlaySoundEvent`. +Sometimes, the event name is prefixed with `Do…`, e.g., `DoDamageEvent`. +You may also encounter event names ending on `…RequestEvent`. + +> 💡 When looking at trigger events from the receiver's perspective we can differentiate between _implicit_ and _explicit_ trigger events. +> +> On the one hand, events which are deliberately sent by a system to trigger an action are _explicit triggers_. +> On the other hand, a system can react to any [Notification Event](#notification-events) or observed change to start a process. +> We consider these causes _implicit triggers_. + + +- 🔗 [Sending Events](Events-and-Systems.md#sending-events) + +## Notification Events + +> Hey, this thing happened. + +The intent of a _notification event_ is to inform that something happened. +The sending system makes a statement about something it has observed or done. + +Terasology comes with a basic set of [entity life cycle events]() which notify about state changes of entities (e.g., added, changed, or removed components). +This allows other systems to react on these changes - our foundation for game logic. + +The reasons for dedicated notification events are manifold. +They can inform about the result of a process, a filtered view on a component change, or describe abstract events. +In all cases, there is a single source of truth assembling the notification event. +This reduces code duplication, as systems can rely on notification events instead of computing the information themselves. + +The sending system is unaware of event listeners. +Thus, it does not expect any action to follow the notification event. + +Examples for notification events are life cycle events (e.g., `OnAddedComponent`), filtered views on component changes (e.g., `OnHealthChangedEvent`), enriched process results (e.g., `OnDamagedEvent`), or abstract events without (direct) representation in components (e.g., `OnBiomeChangedEvent`). + +**Notification events are _immutable_.** +The sending system wants to convey specific information which should not be altered. +This ensures that all systems receive the same information. + +**Notification events are _not consumable_.** +Notifications events inform about a completed action or event. +Consuming the event would withhold the information from other interested systems, and is seldom a good idea. + +A simplified version of the notification event informing that an entity received damage may look like follows. +The event is immutable and not consumable. + +```java +public class OnDamagedEvent implements Event { + // private member, cannot be modified after event creation + private final float amount; + + public OnDamagedEvent(float amount) { + this.amount = amount; + } + + public float getAmount() { + return amount; + } +} +``` + +A system receiving an instance of this notification event can now react ot it. +For instance, the audio system plays a sound asset based on the amount of damage that was dealt. + +> 💡 The notification event acts as an implicit [trigger event](#trigger-events). + +Trigger events are often named in past tense, e.g. `MovedEvent`. +Many notification events are prefixed with `On…`, e.g., `OnDamagedEvent`. +Sometimes, they are named by the subject they describe, e.g, `CollisionEvent`. + +- 🔗 [Processing Events](Events-and-Systems.md#processing-events) + +## Collector Events + +> I'm about to do a thing, any comments? + +The intent of a _collector event_ is to ask systems for their contribution to an action. +The sending system is broadcasting a question to collect contributions from other interested systems. + +Collector events are an extension mechanism to decouple external modifications from the base logic of an action. +The leading system performing an action owns the logic of that action. +The leading system offers controlled extension points via collector events. + +An advantage of collector events is that they work well for temporary modifications. +To revert a modification the respective system simply stops contributing to the collector event. + +By pushing the logic for contributions to downstream systems we can avoid complex orchestration of contributions in the leading system. +The downstream systems act on the collector event independent of each other. + +> To model explicit dependencies and collaboration between systems reacting to a collector event, consider a second level [event flow]. + +Examples for collector events are frequent actions (e.g., health regeneration or movement speed) and one-time events with (potentially many) contributing systems (e.g., damage affected by buffs and reductions). + +**Collector events are _mutable_.** +Collector events are meant to be modified by downstream systems. +For numerical values the event usually extends `AbstractValueModifiableEvent`. +The event handler priority defines the precedence order in which downstream systems receive the event. + +> Collector events may hold _immutable_ information as well to inform downstream systems about the context of the action. +> If the event is sent just to allow cancellation, there may be no mutable properties at all. + +**Collector events are (often) _consumable_.** +Collector events are often consumable to allow a downstream system to cancel the action without any effect. +For more complex decision logic (e.g., majority vote) the collector event may be _not consumable_ but offer other means to express "cancellation". + +A simplified version of the collector event to allow downstream systems to contribute to a damage action. +The event is partially mutable. It is consumable to allow for cancellation. + +```java +public class BeforeDamage extends AbstractConsumableValueModifiableEvent { + // private member, cannot be modified after event creation + private final String damageType; + + public OnDamagedEvent(float baseDamage, String damageType) { + // initialize the ValueModifiableEvent with the base damage value + super(baseDamage); + this.damageType = damageType; + } + + // give additional context to downstream systems + public String getDamageType() { + return damageType; + } +} +``` + +This event is sent against the entity that is about to receive damage. +A system reacting to this event can use the additional (immutable) context given by `getDamageType()` to influence the action, e.g., reduce the damage amount by 2 points if the damage type is `"pierceDamage"`. + +> ⚠️ Collector events should never be used as notification events or trigger events as they can be canceled. + +Collector events are often prefixed with `Before…`, `Affect…`, or `Get…`. + +--- + +Note, that the categorization of events is ambiguous and depends on the point of view. +For instance, an event sent out as notification event by one system may be treated as trigger event by another system. +Some events may also fulfill the characteristics of several event types at once. + +Read more on [event flow] to learn about typical use cases of the different types in a bigger picture. + + +[entity]: Glossary.md#entity +[event flow]: Event-Patterns.md \ No newline at end of file diff --git a/docs/Events-and-Systems.md b/docs/Events-and-Systems.md new file mode 100644 index 00000000000..570fa835073 --- /dev/null +++ b/docs/Events-and-Systems.md @@ -0,0 +1,84 @@ +# Events and Systems + +## Summary + +_Events are sent to exactly 1 entity. Systems can define methods, that get called when specific events get sent to entities with certain components._ + +See also various tutorial modules and examples, such as https://github.com/Terasology/TutorialAssetSystem/wiki/Add-A-Dice + +## Processing events + +To make a class a system you annotate it with the `@RegisterSystem` annotation. If a system implements certain engine interfaces like `UpdateSubscriberSystem`, then the methods of that interface will automatically be called by the engine. In addition to that, systems can declare methods that get called when certain events occurred at certain entities. + +Event processing methods must have the following method signature: +* They must have a `@ReceiveEvent` annotation +* They must be public +* The type of the first argument must implement `Event` +* The second argument must be of type `EntityRef` +* The rest of the arguments (if there are any) must implement `Component` + +The signature determines when the method will be called +* The first argument controls for which type of event the method will be called. +* The `@ReceiveEvent` has an optional attribute called components which takes an array of component classes. The method will only be called if the entity has all those components. +* If there are optional component arguments, then the method will only be called if the event receiving entity has all of those components (like with the components attribute of `@ReceiveEvent`). +* The `@ReceiveEvent` annotation has also a priority attribute. It specifies the order in which this event will be processed by systems that have registered for the same event. +* The `@ReceiveEvent` annotation has also a `netFilter` attribute, which simply spoken specifies whether the event should be processed only on the server, only on the client, or on both. See Javadoc for `RegisterMode` for how it actually works. Usually this network mode gets set globally for the whole class via `@RegisterSystem` annotation. + +All parameters will be filled when the event occurs: +* The first argument will be filled with the event that occurred. +* The second argument will be filled with the entity at which the event occurred. +* The remaining arguments will be filled with the components of the entity, at which the event occurred. As the existence of the components is a requirement for the method to be called, all arguments will be filled out. + +Example: +```java +@ReceiveEvent(components = {MyComponent.class, LocationComponent.class}) +public void onMyComponentAdded(OnAddedComponent event, EntityRef entity, MyComponent myComponent) { +``` +The example method gets called, when the `OnAddedComponent` event occurs at an entity, which has all of the following components: `MyComponent`, `LocationComponent`. The listing of `MyComponent` both in `@ReceiveEvent`and in the component arguments is redundant, but increased readability in the upper case. + +**Note:** Some events like the `OnAddedComponent` event are implicitly linked to a component and will only be offered to methods that require those arguments. In the upper case the event fires only when `LocationComponent` got added while `MyComponent` was present or when `MyComponent` got added while `LocationComponent` was present. When another component gets added, while `MyComponent` and `LocationComponent` are present, the method won't be called. + +The following core events are linked to to a component and require handling methods to require them: +* `OnAddedComponent` +* `OnActivatedComponent` +* `OnChangedComponent` +* `BeforeDeactivateComponent` +* `BeforeRemoveComponent` + +All other core events and probably all module events aren't linked to a component. Please read the Javadoc of any event you make a system for. + +## Defining events + +An event is a class that implements the interface `Event`. + +Its fields should be private and should be made accessible via public getters. The event should have no setters but a constructor that takes the values for all fields and sets them. + +For events that are intend for network transfer, a protected default constructor should be provided. + +See also the next chapter for annotations that are necessary for having an event be transferred over the network. + +## Sending events + +The recommended way of sending events is via the send method of entities (see `EntityRef#send`) +```java +entity.send(new MyEvent(myArg1, myArg2)); +``` + +Per default, events aren't sent over the network. + +Events annotated with `@ServerEvent`, are sent to the server. Only systems on the server will then be able to process it. Typically those events are requests to the server to confirm a gameplay related change. For that reason their name often ends with Request instead of Event. + +Events annotated with `@BroadcastEvent` are sent by the server to all clients. +* TODO: What happens if a client tries to send this event? + +Events annotated with `@OwnerEvent` are sent by the server to the client that owns the entity. Typically a client only owns its character and stuff related to it. + +If a system on a client/server is responsible for processing an event, it can and should also be defined via a network filter which can be specified in the `@RegisterSystem` annotation of the service or within `@ReceiveEvent` annotation of the handling method. + +## Consumable events + +Normally an event is processed by the event handling methods in the order of their priority. Events that implement `ConsumableEvent` can, however, be consumed. Once an event is consumed its event handling stops and the remaining event handlers (with lower priority) do not see the event. + +This is for example useful to determine what happens with user input: When the player is in a mine cart the input movement events may be consumed by a high priority mine cart event handler before they reach the normal movement handlers. + +The sender of consumable events can check if their event got consumed. Some consumable events are sent as a test to figure out if there is a new system that objects with the action being taken. For example the event `BeforeItemPutInInventory` can be consumed by a new system, to prevent the placement of items in a slot that is reserved for certain other items. \ No newline at end of file diff --git a/docs/GCI.md b/docs/GCI.md new file mode 100644 index 00000000000..472ce2f819b --- /dev/null +++ b/docs/GCI.md @@ -0,0 +1,161 @@ +# Google Code-In + +As with [Google Summer of Code](GSOC) we participate in [Google Code-In](https://developers.google.com/open-source/gci/) when able. We welcome students to contribute to Terasology while learning about open source :-) + +GCI groups tasks for students into five categories. Below are some general guidance for what kinds of tasks may be encountered and how they relate to the open source way. + +**BIG NOTE**: Terasology is _Alpha level software_ - expect bugs and crashes! Just about any task could potentially be blocked if a bug gets in the way. If you see something that doesn't seem right or makes a task unexpectedly difficult, reach out to a mentor or ask on [chat](https://github.com/MovingBlocks/Terasology/wiki/Using-IRC) to find out if you're on the right track or hitting a problem we may need to check on. Don't fret - ask! :-) + +**Need help in finding an easy next task?**: Head over [here](https://github.com/MovingBlocks/Terasology/wiki/GCI#recommended-tasks). + +**Want a nice one-page overview of the main stuff from setup through coding stuff and understanding our architecture?** See [this wiki page](https://github.com/casals/terasology-101/wiki/Terasology-Dev-101) + +## Projects + +### Terasology + +Terasology has grown over the years and has hundreds of repos across different GitHub organizations at this point as well as multiple websites/services. We have a whole other game now and also consider options to be an umbrella org for smaller open source groups interested in GCI :-) + +The game engine project and all our content modules remain our primary focus for GCI and make up most the tasks. There will be a lot of introductory tasks for base systems and research tasks on trying or testing something out and writing about the experience. Attempting to make some cool new content via other tasks is popular as well. Side tasks like looking at secondary projects/tool can be found as well. + +### Destination Sol + +Our second game is [DestSol](https://github.com/MovingBlocks/DestinationSol) - a simple and fun little 2D space shooter we adopted into the open source community from a team that used it as an experimental title to get on to Steam and Google Play (Android). Fly around in a variety of ships blasting enemies and asteroids with a bunch of different weapons. Then [make more of them](https://github.com/MovingBlocks/DestinationSol/wiki/Adding-content-to-Modules) as part of GCI tasks! + +## Task Categories + +For each project or sub project you will find a variety of types of tasks. GCI contains 5 primary categories although tasks may involve several at once. The below categories refer mostly to Terasology specific tasks but should give you an idea of what to inspect in general as well. + +### Coding + +Getting into the code itself might seem the most natural way to participate in an open source project, and it is often the most critical. After all, what is open source without _any_ source? + +For these tasks you'll likely need a code workspace so you can run the game from source. The [quick start guide](Dev-Setup) is a good place to start, and there are several more resources in the wiki's sidebar. Alternatively, newcomers to the code will sometimes write about their experiences setting up - for instance, check out [this guide by Nihal Singh](http://nihal111.github.io/2016/11/22/Terasology-Getting-started.html)! + +Recommended tasks to start with for coding are (TODO task link) "setting up to run from source" and then (TODO: task link) "creating a new block". + +#### Structure Templates + +One of the big content formats in Terasology involves writing files in JSON, of which Structure Templates (STs) feature prominently in GCI tasks. While the JSON file handles the config of the ST-based content it can usually be generated via in-game tool allowing you to mark an area you've built by hand and turn that into a big text file. Read about them more [in the forum](http://forum.terasology.org/threads/structure-templates.1550) + +As part of fashioning ST-based content you may also need additional artwork or functionality requiring new or updated Java code. + +### Documentation / Training + +Sadly a lot of projects, both open source and proprietary, do not get to spend a sufficient amount of time and effort on documentation and training for users and contributors alike. We have a fair amount of documentation and guides, but definitely need more! + +This area is especially important to open source as it is often the first thing you see if you are interested in contributing. Without great documentation and a friendly supporting community it is hard to learn. + +Documentation can also be a way to get into code gently - by reading and trying to understand what something does, then documenting it better using Javadoc or small wiki guides. You can easily submit documentation updates as [pull requests](https://help.github.com/articles/about-pull-requests/) on GitHub, then clarify any points you are unsure of during the review phase. Wiki pages can be done first as drafts with a mentor or other community member reviewing at your request. + +Beyond the game we maintain multiple websites and other services, and occasionally release videos on YouTube. Guides and training in video form is another nice-to-have area 🙂 + +#### JavaDoc + +Some tasks call for the creation or enhancement of code comments that become part of the source and something you can generate external documentation from. There are plenty of undocumented stuff to pick from *but* note that we often use multi-instance generic "Document something!" tasks that mean you could end up picking the same code to document as another student. Keep an eye out for any details in tasks about coordinating what you're working on to avoid overlap and wasted work. + +You don't need to fully understand a whole system to be able to write JavaDoc for smaller pieces, but you do need to be able to do the detective work to figure out some of the parts. You can't just ask mentors what things do - but during review of the PR you can get your theories validated / corrected :-) + +### Outreach / Research + +Some projects are able to spread by pure word-of-mouth and/or by simply releasing their software on existing marketplaces. Plenty of others wouldn't be found easily without some significant effort by community members. + +Terasology has spent most its time in self-imposed _stealth mode_ as we have been heavily focused on the architecture of our engine, finding ways to support content that would set our game apart in some novel fashion. However, we believe we have reached a point where the ability to make interesting new content has run far ahead of what actual content we have, and partly thanks to GSoC and GCI we are trying to come out of our shell to find new users and contributors. + +As part of that process starting to reach out to more contributors and potential players is becoming more important, as is researching what is going on in our ecosystem these days. + +#### Try something out, report on how it went + +One type of task in this area is pretty simple: play a specific part of the game, then tell us what went well and what could be improved :-) + +In addition to reporting back with details you can publish videos showing off large builds, howtos, showcases, or just about anything. + +Better yet: find a friend or two and introduce them to the game for a little while in multiplayer, then record their reactions. Or if you set up for coding let us know how that process went, and then talk a friend through the same process to see how they experience it differently. + +We rely on user reports to determine what we should work on, in what order. Since we've spent so much time just being developers around other developers we need your help! + +### Quality Assurance + +Oh right, testing things! We should totally do that. Anybody? :D + +There is an immense amount of testing technology and methodologies out there, and web applications in particular can apply heavily automated testing procedures, driving a browser to follow a script and validate that everything happens as expected. + +Video games on the other hand are trickier. The automated tools still work at the code level and unit testing plus code analytics can help keep your code healthy. However outright testing how the game plays is much more difficult and usually a manual process. This is especially the case with all-volunteer open source where we might not have access to expensive tools. + +Traditionally we've relied on our developers to check that their own code works in-game, but it is very easy to miss things as the game gets more complicated. Before we do a stable release we usually run through the very beginning of some of our basic content, but do not go very deep. It is time to get more serious about testing! + +#### Test Plans + +A large new field we are aiming to approach in part via GCI is running through manual test plans like how you would manually follow a script on a website, recording results. For web apps you can automate that part, but we have to rely on manual testing for now. + +To formalize what we should be testing we need to first write actual test plans - a script you follow exactly inside the running game. For example: + +* Run the game via executable +* Validate that the game appears and that music starts playing +* Go to the create new game screen and make sure you see `x` `y` and `z` UI elements on the screen +* Start a game with the default settings +* Validate that you load into a world and have items `a` `b` and `c` on your toolbar +* Place the chest from your toolbar on the ground +* Validate that the chest appears, that you can open it by `e` clicking it, and see that it contains more stuff + +The above would make up a single "test case" - a series of them can be grouped into a "test suite" where you might test out several related features in one testing session. A test plan would cover a distinct area, such as the base game. Another test plan could aim to validate a particular series of modules instead of the base game, such as the JoshariasSurvival gameplay template. + +An added difficulty is that thing about us being in **Alpha** - even trying to write a single test case may end up getting blocked if a bug gets in the way and breaks forward progress through a tech tree, for instance. In that case you may need to contact your mentor or ask on IRC, and work on other test cases in the meantime. + +You may want to use [the latest stable release](https://github.com/MovingBlocks/Terasology/releases) to base your testing on rather than the current develop build, since it may be more unstable. If you still encounter issues you might want to try the other build to see if it works in either. + +Additionally being new to the project you may not know _what_ to test, since we don't have any test plans yet! Individual tasks should give you pointers on what to look for, but you may also need to experiment in-game (sometimes there is a recipe browser), watch showcase videos, or even look at the code to find out what content exists. The game console can be very useful with commands like `listBlocks` or `search`. Finally you might be able to get a hold of individual authors to ask questions about how something is expected to work. + +#### Module Testing Environment & Recordings + +Beyond simple unit tests written as part of the code or manual test plans humans can work through we have [game environment based tests](http://forum.terasology.org/threads/moduletestingenvironment-integration-testing-with-in-process-engine-objects.1884) that can automatically validate in-game behavior with both the server and connected clients being "headless" - not attached to a monitor or a keyboard/mouse. + +Those kinds of tests can be incredibly valuable as it allows us a good degree of confidence that actual gameplay should be working as we change things. Some tasks will ask for these kinds of "advanced" unit tests and are hugely appreciated! + +Even newer than the MTE is a [Record & Replay system developed during GSOC 2018](https://forum.terasology.org/threads/record-and-replay-feature.2183) - this is akin to the MTE but works by having a player record a play session in-game, then add assertions at specific times that a condition was present. + +### Design (old User Interface) + +Renamed from plain "User Interface" for GCI 2018 this category now includes everything "Design" ... which is what, really? :-) + +We're not actually sure! It still could be considered to involve UI, but maybe now moreso also User Experience (UX) or even game design elements like writing specifications for new gameplay. We doubt it involves developing the latest fashion for use on a catwalk, but technically you _could_ implement that in a new gameplay template! + +While even UI work alone could be considered a subset of coding it can call for a subtly different skillset from traditional programming. At the UI level you get into ["User Experience Design" or UX](https://en.wikipedia.org/wiki/User_experience_design), which in a way is to the game as the documentation is to the project: you need to make sure it looks and feels right on the first impression! + +We have our own UI framework with the cool extra that you can edit the game's UI from inside the game itself, seeing the UI elements update in real time. We also have a [tutorial for the framework and editor](https://github.com/Terasology/TutorialNui). + +What we don't really have is a broad selection of users from different backgrounds that have tried out the game and let us know what part of the UI works well and which parts could use some work. Sometimes making adjustments or even trying out a few different approaches is easy enough where you can try it out and share the experience with a friend or two. + +## Recommended Tasks + +Here's a list of easy, suggested and easily approachable tasks that can be completed with little to no knowledge of programming. If you find yourself stuck after having completed two beginner tasks or don't know which task to choose next, this list is for you! + +### Beginner tasks + +* [Set up a local workspace and run Terasology from source](https://codein.withgoogle.com/dashboard/tasks/5667069010378752/) +* [DestSol - Set up a local workspace and run Destination Sol from source](https://codein.withgoogle.com/dashboard/tasks/5667069010378752/) +* [World Generation Chain (I) : Make a Basic World Generator](https://codein.withgoogle.com/dashboard/tasks/6630038057779200/) +* [Set up a Terasology server, provide usability feedback](https://codein.withgoogle.com/dashboard/tasks/6456084567425024/) +* [Create your owh GitHub module repository](https://codein.withgoogle.com/dashboard/tasks/5980461365460992/) +* [Research events for theming DestSol](https://codein.withgoogle.com/dashboard/tasks/5534877064101888/) + +### Intermediate tasks + +* [Behavior Chain (I): Create behaviors for characters](https://codein.withgoogle.com/dashboard/tasks/5656125752475648/) +* [Tutorial ECS: Learn how Terasology works and write about it!](https://codein.withgoogle.com/dashboard/tasks/6507050293526528/) +* [Write unit tests for the TeraMath project](https://codein.withgoogle.com/dashboard/tasks/4824882966167552/) +* [DestSol: Make your own faction!](https://codein.withgoogle.com/dashboard/tasks/4965113916817408/) + + +### Content focus areas + +Terasology has a series of gameplay templates that provide a content base for playing the game in a particular way. Tasks in these areas will tend to be both useful and fairly easy. Here are some introductions to a few such areas. + +#### Master of Oreon + +Also known as "MOO" this setting has the player serving as a care taker for some "Oreon" creatures that can perform a variety of tasks like constructing buildings, farming, practicing their skills, researching new abilities, and so on. This is our main take on gameplay like that found in Dwarf Fortress or Dungeon Keeper and it was [heavily updated as part of GSOC 2018](https://forum.terasology.org/threads/master-of-oreon.1015/post-16075) now needing further expansion on available tasks, structures, food, behavior, etc. + +Here are some of the tasks related to MOO: + +* [Create a new building of your choice!](https://codein.withgoogle.com/dashboard/tasks/6465370823589888/) +* [Create new crops for planting (I)](https://codein.withgoogle.com/dashboard/tasks/5057108660191232/) \ No newline at end of file diff --git a/docs/Home.md b/docs/Home.md new file mode 100644 index 00000000000..290db444805 --- /dev/null +++ b/docs/Home.md @@ -0,0 +1,58 @@ +Welcome to the Terasology Wiki! + +This is a wiki for those interested in contributing to the development of the project. + +It doesn't cover game content or how to play the game much, but check out the docs on [Playing](https://github.com/MovingBlocks/Terasology/blob/develop/docs/Playing.md) (including hotkeys etc) and [Modules](https://github.com/MovingBlocks/Terasology/blob/develop/docs/Modules.md) for some of that. + +Use the sidebar to arrive at the most central topics this wiki covers. + +See [What is Terasology](What-is-Terasology.md) for some more background information. + +## Joining the Community & Asking for Help + +Our main place of communication is on our [Discord Server](https://discord.gg/terasology). +Make sure to check in, introduce yourself and what you're interested in with regards to Terasology :wave: +For any playing related issues, leave us a note in the `#play-terasology` channel. +Troubleshooting workspace setup, compile / test issues or other development related issues can be raised in the `#terasology` channel or by [opening an issue on this repo](https://github.com/MovingBlocks/Terasology/issues/new/choose). + +Our [forum](https://forum.terasology.org/forum/) is currently mainly used to track progress of our GSoC student projects. +However, it has a lot of more or less actionable ideas for improvement and a bunch of history of our current gameplays floating around, so feel free to roam around a bit and get inspired :wink: + +## Contributing + +Interested in getting involved with working on the game? Make sure to check out the [Contributor Quick Start](Contributor-Quick-Start.md) for setting up your first workspace and starting the game from source. It also has useful links on how to start with your first contribution. + +We also apply for GSOC - [Google Summer of Code](https://developers.google.com/open-source/gsoc) and [GCI](GCI.md) - [Google Code-In](https://codein.withgoogle.com/) every year. So if you're a student and it is that time of the year maybe check it out! + +## Architecture + +Terasology is build from many building bricks, that together turn into a game. + +The _engine_ forms the core, and resides alongside the default _facade_ and _subsystems_ in ([MovingBlocks/Terasology](https://github.com/MovingBlocks/Terasology)). + +This core is backed by several in-house _libraries_, such as([MovingBlocks/gestalt](https://github.com/MovingBlocks/gestalt)) providing the entity system and module management, or our own UI library ([MovingBlocks/TeraNUI](https://github.com/MovingBlocks/TeraNUI)). +The actual game content is added by _modules_ on top of that. + +All Terasology modules reside in the [Terasology](https://github.com/Terasology) Github organization. + + + +These pages offer more advanced insight into how specific features of the game are architected and why. + +- [Project Sturcture](Codebase-Structure.md) - a high-level overview of the code base +- [Entity System Architecture](Entity-System-Architecture.md) - describes the structure and usage of the entity system. +- [Events and Systems](Events-and-Systems.md) - describes how new game logic can be hooked in +- [Block Architecture](https://github.com/Terasology/TutorialAssetSystem/wiki/Block-Attributes) - development overview of our Block system. (pending changes needed to make the game work in an applet again) +- [Block Shapes](Block-Shapes.md) - defining 3D meshes via definitions in JSON! + +## Announcement Channels + +We have several ways to get the word out on updates, likewise, there are several ways to contact us. + +- [Discord](https://discordapp.com/invite/terasology) - New development/game topics will be posted in `#announcement`, and any questions answered. +- [GitHub (Engine)](https://github.com/MovingBlocks/Terasology) - "Watch" the official project here to be able to easily spot core commits and changes. +- [GitHub (Modules)](https://github.com/Terasology) - "Watch" the module repos to be able to keep track of game content fixes / changes. +- [Forum](http://forum.terasology.org/) - Find the progress reports of ongoing and past GSoC projects along with a lot of gameplay ideas and lore +- [Twitter](http://twitter.com/#!/Terasology) - We'll tweet regularly about significant commits or new discussion topics posted, so "Follow" us for updates. +- [Facebook](http://www.facebook.com/pages/Terasology/248329655219905) - If you prefer to keep updated via Facebook you can "Like" us on there to keep up. +- [Jenkins RSS](http://jenkins.terasology.org/rssAll) - If you really want to know when something has just been built ;-) diff --git a/docs/How-to-Use-Record-and-Replay.md b/docs/How-to-Use-Record-and-Replay.md new file mode 100644 index 00000000000..34809a8fd5c --- /dev/null +++ b/docs/How-to-Use-Record-and-Replay.md @@ -0,0 +1,19 @@ +# How to use Record and Replay + +## Overview + +Record & Replay is a feature created with the intent to improve Terasology's Quality Assurance by recording some events of specific types during a singleplayer session and then replay them to see if everything was reproduced accordingly. This is especially useful when a recording is made in a game version and it is replayed on future game versions to check if something was broken. + +## Recording a single-player session + +To record a game, it is necessary to first have a created game. If there is no singleplayer game, create one normally by clicking the "Singleplayer" button. +Once there is at least one singleplayer game, click on the "Extras" button in the Main Menu, which will lead to another screen. On this new screen, click on the "Record" button, select a game to record and then click "load". The game will load normally as it would in a normal Singleplayer game, but once the game is loaded, some events will be recorded. Play the game normally, and when you wish to stop the recording, just exit to the main menu or exit the game. Once that's done, notice that a new folder called "recordings" was created, and inside it, there will be another folder with the name of the world that was recorded. In this folder, there will be the save files and also some files with recorded events and other parameters important for the replay. + +## Replaying a single-player session + +To replay a game, just click on the "Replay" button on the extras menu and then select a recording to load. Once the game is loaded, notice that you won't have control over your character, since it is not possible to normally send the events of the same type of the ones recorded during a recording. For example, since InputEvents are recorded, it is not possible for the player to send InputEvents during a replay. A few seconds after the replay is loaded, the actions made during a recording will begin to be replayed. Once every recorded event is replayed, you will have control over your character again. + +## Important Information + +* As of now, recording the game that uses a Module that implements new types of InputEvents that are not BindButtonEvent or BindAxisEvent may cause issues in the replay if said events are executed during a recording. +* It is known that sometimes "right click" causes some issues in a recording, especially if the button is held during a replay, which may result in a few blocks being placed on wrong locations during a replay. diff --git a/docs/How-to-Work-on-a-PR-Efficiently.mediawiki b/docs/How-to-Work-on-a-PR-Efficiently.mediawiki new file mode 100644 index 00000000000..1de9e314a67 --- /dev/null +++ b/docs/How-to-Work-on-a-PR-Efficiently.mediawiki @@ -0,0 +1,66 @@ +== Introduction == +The first thing to understand when you submit a Pull Request (PR) is that you are asking for somebody's else Time. + +Somebody has to spend time to review the PR, test it and then merge it, the review part usually being the most time-consuming. + +This page intends to offer some clear guidelines on how to structure your PR process to minimize Reviewer's time and maximize the efficiency of the process. + +== Executive Summary == +* Talk to People +* Produce good code and structured commits +* Keep it Small +* Write a solid Description +* Use GitHub well + +== How To Work on a PR Efficiently == +===Step 0 for an efficient PR: before you even start writing code=== +* '''Talk to the people who would be in the position to review and approve the changes you have in mind.''' +** Ideally these are people who are actively working in that area or have worked on it in the past. +* '''Make sure they agree with the general direction of the changes you intend to propose.''' +** Work out with them, in written form (diagrams, bullet points), the broad strokes of what you intend to do. +** You will waste your time if you don't. +** Changes envisioned by contributors that are known to be good at handling feedback are more readily embraced.''' +* Some areas have been left "orphan" by the ebb and flow of contributors over time. +** On one hand there's the opportunity for you to become the new curator of an area. +** On the other hand you will need approval from people that do not know much about that area, requiring an extra communication effort to clear with them what you are doing. + +===Step 1 for an efficient PR: before you even submit a PR=== +* '''Write well readable, well maintainable code that does the job''' - that's a given or your code won't go anywhere. +* '''Self-documenting code is good, but usually not enough.''' Javadocs and inline comments remain necessary. +** Javadocs for public methods ''may'' be postponed to the latter phase of a PR process, but Javadocs for public classes are usually necessary right away, especially when new classes are introduced or existing classes are changed significantly. +** Inline comments should document why the code is the way it is, not what it does. +* '''Take advantage of your commits and their descriptions to document your steps.''' +** A reviewer may look at the changes brought by individual commits, to review one step at the time. +* '''The best results can be achieved by working on an exploratory branch first.''' +** Once you are happy with the results, start a new branch from scratch and replicate the changes, this time with a reviewer in mind and with the intent of creating a neat and tidy set of changes. +** Make sure to group closely-related commits by squashing them into one commit. +** Also group trivial changes in isolated commits (i.e. refactoring the order of methods or renaming a class) and clearly mark them as such, so that a reviewer can quickly skim through them. + +===Step 2 for an efficient PR: keep it small=== +* Ideally you want to change ''significantly'' at most 10-20 files in one PR. +* It is possible and sometimes necessary to change many more files, but the large majority of the changes should then be trivial consequences of significant changes in 10-20 files at most. +* Significant changes to large number of files can usually be handled via multiple consecutive PRs. +* '''PRs significantly changing large number of files tend to require exponentially longer time to review.''' +** In extreme cases, PRs that are too big may be left unreviewed and, eventually, may be closed as obsolete. + +===Step 3 for an efficient PR: write a solid description for it=== +* Whenever you submit a PR a default template appears as the initial description: take advantage of it and fill it in. +** Feel free to partially or completely deviate from the default template, if it makes sense. +* '''The description of medium to large changes, as well as potentially controversial changes, should show some effort.''' +** You might want to draw attention to the changes in specific files as the most significant, declaring other changes trivial consequences of the significant changes. +** You might also want to draw attention to specific commits, where the most significant changes are, declaring other commits as trivial. +** See PR [https://github.com/MovingBlocks/Terasology/pull/3199 #3199] and [https://github.com/MovingBlocks/Terasology/pull/3227 #3227] for some descriptions that clearly took a good effort to write. +** See also [https://github.com/MovingBlocks/Terasology/pull/1459 #1459] for a more compact description that still shows some effort. +* Large PRs like [https://github.com/MovingBlocks/Terasology/pull/3535 #3535] may also link to the files/classes with the most important changes in a "Review guide" to make it easier for reviewers. + +===Step 4 for an efficient PR: use GitHub well=== +* Once you have submitted a PR, feel free to add your own GitHub comments to pieces of code you wish to draw attention to. +** I.e. to have a second opinion on a specific section you are not fully convinced about. +* '''When the feedback arrives do not rush to push new commits:''' +** When you push new commits you may hide conversations that haven't reached a conclusion. +** Ideally, every conversation should end with a thumb up from you or from the reviewer, before new commits are pushed. +** And your own thumb up should mean: "I made the requested changes locally" - it's a good way to keep track of what you did and didn't yet, before you push the new commits. +* One thing to not use GitHub for: Editing files on the website using the GitHub code editor in your browser. This bypasses a lot of checks that local code editors / IDEs do well, like matching existing whitespace and actually validating that code still compiles. + +== Conclusion == +By taking onboard these guidelines the process leading to your code being merged in should be faster and smoother, for both you and the people reviewing your PRs. diff --git a/docs/IO-API-for-Modules.md b/docs/IO-API-for-Modules.md new file mode 100644 index 00000000000..0e37ad45985 --- /dev/null +++ b/docs/IO-API-for-Modules.md @@ -0,0 +1,49 @@ +I/O API for Modules +================= + +To protect the user's system, you cannot use `java.io.File` directly, however a bunch of modules may need access to files. Finally, this feature allow modules to have **limited** access to files. Basically, there are two file operations allowed, `readFile` and `writeFile`, both of them works under the `Terasology/sandbox` directory. Take a look on the instructions bellow to learn how to use them. + +1. The first step is to import and initialize the sandbox file manager where you need it, for this you can do the following: +```java +SandboxFileManager sandboxFileManager = new SandboxFileManager(); +``` +2. Second, create a consumer. We have two different types of consumers. +* Read file consumer: +```java +// put whatever you need here +byte[] someBytes = new byte[2]; + +Consumer consumer = outputStream -> { + try { + outputStream.write(someBytes); + } catch (IOException e) { + // error + } +}; +``` +* Write file consumer: +```java +Consumer consumer = inputStream -> { + try { + int value = inputStream.read(); + + while (value != -1) { + doSomething(value); // call your method here + value = inputStream.read(); + } + } catch (IOException e) { + // error + } +}; +``` +3. The third and final step is to call any of the `SandboxFileManager` methods you need. For both methods, it is mandatory to pass in their respective consumer and the file name. +* Read file method: +```java +sandboxFileManager.readFile("file.txt", consumer); +``` +* Write file method: +```java +sandboxFileManager.writeFile("file.txt", consumer); +``` + +Finally, if you wrote any file, you can see them in `Terasology/sandbox` directory. :smiley: \ No newline at end of file diff --git a/docs/Interactive-Blocks.md b/docs/Interactive-Blocks.md new file mode 100644 index 00000000000..c13bb575141 --- /dev/null +++ b/docs/Interactive-Blocks.md @@ -0,0 +1,141 @@ +This is a guide on how to make a block which the user can interact with. + +## Block Definition + +First of all, we need to define the actual block. +A block is a JSON file ending with `.block`. +It needs to be placed in the `assets/blocks` directory. + +Example: To add a HiddenChest block to the module Furnishings you would put the file under: `modules/Furnishings/assets/blocks/HiddenChest.block` + +The block file is json. For the start we will put the following content into the text file: + +```json +{ + "attachmentAllowed": false, + "rotation": "horizontal", + "tiles": { + "sides": "CoreAssets:GreenLeaf", + "front": "CoreAssets:ChestFront", + "topBottom": "Core:ChestTopBottom" + }, + "entity": { + "prefab": "Furnishings:HiddenChest" + }, + "inventory": { + "stackable": false + } +} +``` + +With the tiles object it is possible to specify cube like blocks with up to 6 different textures on the side of the block. +The properties of the `tiles` object should reference textures by their asset URI: ` : ` (learn more in the [Asset System Tutorial](https://github.com/Terasology/TutorialAssetSystem/wiki)). +Any image under `assets/blockTiles` in module can be referenced that way. + +For more details about the block properties have a look at [Block Definitions](Block-Definitions.md). + +## Block Entity + +With the `entity` property of the block it is possible to specify which entity is representing the block. +The sub property `prefab` takes a prefab identifier. +Like with texture identifiers, the value before the colon specifies the module in which the prefab is in. +The value after the colon specifies the extension-less filename of the prefab. +Prefabs files should be placed in the `assets/prefabs` directory and must have the extension `.prefab`, e.g., `assets/prefabs/HiddenChest.prefab`. + +In a prefab you specify which components your entity has by default. +Every class that extends from Component can be used as a property in the prefab file. +All component classes end with "Component". +The property has the same name as the component class except that it lacks the suffix. +For example, an instance of the InteractionTargetComponent class can be added to the prefab by adding a property called InteractionTarget. + +The following prefabs makes the block behave like a chest with 4 item slots: + +```json +{ + "Inventory": { + "privateToOwner": false, + "itemSlots": [0, 0, 0, 0] + }, + "PlaySoundAction": { + "sounds": "engine:click" + }, + "InteractionTarget": {}, + "InteractionScreen": { + "screen": "engine:containerScreen" + } +} +``` + +The Inventory component makes the entity have an inventory. +The 4 zeros mean that there should be 4 empty slots. + +The PlaySoundAction component makes the entity play a sound when it gets activated with E (default key binding). + +The InteractionTarget component makes it possible to start an interaction with the component by pressing E while the cursor is on the block. +An interaction for itself is invisible to the user, until you add a visualization for it. + +The InteractionScreen component makes it possible to specify an UI screen, which will automatically be opened when the user starts an interaction with the block. +Closing that UI will automatically end the interaction with the block. +The InteractionScreen component has a property called `screen` that specifies which UI should be opened. + +## Block Interaction UI + +The look of a UI can be specified with text files that end with `.ui`. +Those text files need to be placed in the `assets/ui` folder of the module. + +For a quick start we will make a copy of the `containerScreen.ui` found in the engine and place it under `assets/ui/HiddenContainer.ui` in our module. +If you placed the UI file in the Furnishings module then you need to change the screen property of the InteractionScreen component to `Furnishings:HiddenContainer`. + +Then we can make adjustments to the UI. +For example, we could make the container grid be 2x2 by changing the `maxHorizontalCells` property of the container grid to 2: + +```json +{ + "type": "ContainerScreen", + "contents": { + "type": "relativeLayout", + "contents": [ + { + "type": "InventoryGrid", + "id": "inventory", + "maxHorizontalCells": 6, + "layoutInfo": { + "use-content-width": true, + "use-content-height": true, + "position-right": { + "target": "CENTER", + "offset": 16 + }, + "position-vertical-center": {} + } + }, + { + "type": "InventoryGrid", + "id": "container", + "maxHorizontalCells": 2, + "layoutInfo": { + "use-content-width": true, + "use-content-height": true, + "position-left": { + "target": "CENTER", + "offset": 16 + }, + "position-vertical-center": {} + } + } + ] + } +} +``` + +## Adding logic + +The structure of the UI file is simple. +The topmost `type` property specifies the name of the Java class that should be created. +The other properties specify the default configuration of that Java class. +The type fields in the substructures describe again which Java class is providing logic to that sub structure. + +The top base class should extend either CoreScreenLayer or BaseInteractionScreen. +The latter is just an enhanced CoreScreenLayer with a simpler way of accessing the interaction target / the block entity. + +In the initialize method you can then access the sub components by using a find method to search the sub components by the id you specified in the `.ui` file. diff --git a/docs/LightEnvironment/Branch.png b/docs/LightEnvironment/Branch.png new file mode 100644 index 00000000000..ff2046575d9 Binary files /dev/null and b/docs/LightEnvironment/Branch.png differ diff --git a/docs/LightEnvironment/Branch1.png b/docs/LightEnvironment/Branch1.png new file mode 100644 index 00000000000..d118f77b83d Binary files /dev/null and b/docs/LightEnvironment/Branch1.png differ diff --git a/docs/LightEnvironment/Branch2.png b/docs/LightEnvironment/Branch2.png new file mode 100644 index 00000000000..d8f9f62cd34 Binary files /dev/null and b/docs/LightEnvironment/Branch2.png differ diff --git a/docs/LightEnvironment/Clone.png b/docs/LightEnvironment/Clone.png new file mode 100644 index 00000000000..71e4d407ca1 Binary files /dev/null and b/docs/LightEnvironment/Clone.png differ diff --git a/docs/LightEnvironment/Commit.png b/docs/LightEnvironment/Commit.png new file mode 100644 index 00000000000..74915fcbc1a Binary files /dev/null and b/docs/LightEnvironment/Commit.png differ diff --git a/docs/LightEnvironment/Create.png b/docs/LightEnvironment/Create.png new file mode 100644 index 00000000000..7df973a0c2b Binary files /dev/null and b/docs/LightEnvironment/Create.png differ diff --git a/docs/LightEnvironment/Delete.png b/docs/LightEnvironment/Delete.png new file mode 100644 index 00000000000..1a7a877db12 Binary files /dev/null and b/docs/LightEnvironment/Delete.png differ diff --git a/docs/LightEnvironment/Edit1.png b/docs/LightEnvironment/Edit1.png new file mode 100644 index 00000000000..cf3b0ae2c4d Binary files /dev/null and b/docs/LightEnvironment/Edit1.png differ diff --git a/docs/LightEnvironment/Edit2.png b/docs/LightEnvironment/Edit2.png new file mode 100644 index 00000000000..f43fa8be732 Binary files /dev/null and b/docs/LightEnvironment/Edit2.png differ diff --git a/docs/LightEnvironment/Fork.png b/docs/LightEnvironment/Fork.png new file mode 100644 index 00000000000..c0f3b3f9cf0 Binary files /dev/null and b/docs/LightEnvironment/Fork.png differ diff --git a/docs/LightEnvironment/PR.png b/docs/LightEnvironment/PR.png new file mode 100644 index 00000000000..630d623c4dc Binary files /dev/null and b/docs/LightEnvironment/PR.png differ diff --git a/docs/LightEnvironment/PR_desktop.png b/docs/LightEnvironment/PR_desktop.png new file mode 100644 index 00000000000..33c84bb17ef Binary files /dev/null and b/docs/LightEnvironment/PR_desktop.png differ diff --git a/docs/Maintenance.md b/docs/Maintenance.md new file mode 100644 index 00000000000..70f5d594986 --- /dev/null +++ b/docs/Maintenance.md @@ -0,0 +1,81 @@ +## How to archive a module? + +You moved the contents of a module into other modules and now the old one is empty? +You cleaned broken and deprecated code out of a module and now it's empty? +You found a module, that is not used anymore and won't be in the near future but is fully functional? +You found a module that wasn't tested for ages and is probably just broken? + +Well maybe it's time to archive that module. + +### Prerequisites + +The following steps are required before archiving: + +* Remove the module name from any distro's `gradle.properties` file in the [`Index` module](https://github.com/Terasology/Index/tree/master/distros) +* Remove the module name and description from the [engine's module list](https://github.com/MovingBlocks/Terasology/blob/develop/docs/Modules.md) +* Remove the module dependency from any other module's `module.txt` file + +### Archiving unused modules + +Modules that are simply currently not in use (and won't be in the near future) are welcome to stay in the ["Terasology" GitHub organization](https://github.com/Terasology). + +For these, you can simply (if you have the required permissions) go to the module's repository settings, scroll down to the very bottom and click on "Archive this repository". This will mark the repository as archived and read-only. Thus, if it gets traction again, + +### Archiving broken / deprecated modules + +Modules that are broken or deprecated or whose contents were moved into other modules - to cut it short modules that "won't be coming back" - should be removed from the "Terasology" GitHub organization. For these modules, we have a dedicated ["Terasology-Archived" Github organization](https://github.com/Terasology-Archived). + +To archive such a module, you can (if you have the required permissions) go to the module' repository settings, scroll down to the very bottom and click on "Transfer". This will open up a form asking for the new organization this repository should be moved to. Enter "Terasology-Archived" and confirm. + +_Please note, that you need to have permissions to create repositories in "Terasology-Archived" to be able to do so._ + +## How to restart the Artifactory + +Prerequisites: +* Access to Digital Ocean "Terasology" project +* Optionally: SSH key configured on the artifactory droplet + +Instructions: +1. Log in to [Digital Ocean (DO)](https://cloud.digitalocean.com/projects/ef80fed5-434c-450c-848e-f76a6a38667a/resources?i=dae9f4) and make sure you're on the "Terasology" project +1. Click on the "artifactory.terasology.org" droplet +1. If you have an SSH key configured on the artifactory droplet follow the steps below, otherwise go to [cheat-restart](#cheat-restart) +1. Copy the ipv4 address +1. Open a terminal and use SSH to connect to the droplet: `ssh root@ ` +1. Optional: If there is an issue with the artifactory and you know what you're doing, try to investigate the issue +1. Restart the artifactory: `service artifactory restart` +1. End the SSH connection and log out of DO + +### Cheat Restart + +1. If not yet done, log in to [Digital Ocean (DO)](https://cloud.digitalocean.com/projects/ef80fed5-434c-450c-848e-f76a6a38667a/resources?i=dae9f4), make sure you're on the "Terasology" project and click on the "artifactory.terasology.org" droplet +1. In the droplet sub-navigation on the left, go to "Power" +1. Click on "Turn off" and wait until the droplet is successfully stopped +1. Click on "Turn on" and wait until the droplet is successfully running again + +## How to fix an expired GitHub Action token + +The [`project-autoadd`](https://github.com/MovingBlocks/Terasology/blob/develop/.github/workflows/project-autoadd.yml) GitHub action requires privileges on projects to do its work. For this, it uses a Personal Access Token (PAT) with project scope stored in the organization secrets as `PROJECT_GITHUB_TOKEN`. +This PAT may expire at some point in time leading to failures of the GitHub action due to missing privileges. To fix this, you'll need to perform the following steps. Please note, that you'll require administration privileges on the [`MovingBlocks`](https://github.com/MovingBlocks?type=source) organization to modify the organization secrets. + +1. Go to your account's [Settings -> Developer settings -> Personal Access Tokens -> Tokens (classic)](https://github.com/settings/tokens) + +  + +1. Generate a new classic token, give it a name, set an expiry date (recommended: 90 days) and enable the `project` scope (_Full control of projects_). Do not enable any other privileges, they are not needed. + +  + +1. **Note: Do not reload the resulting page before you created the org secret as you'll not be able to see the generated token again!** + + Go to the organization's [Settings -> Secrets -> Actions](https://github.com/organizations/MovingBlocks/settings/secrets/actions) + If you cannot access the settings or secrets, you're probably not an organization admin. Please approach one of the maintainers on our [Discord Server](https://discord.gg/terasology) to support you. + +  + +1. Remove the existing `PROJECT_GITHUB_TOKEN` secret. + +1. Create a new organization secret, name it `PROJECT_GITHUB_TOKEN`, leave the "Repository access" default and copy the token you generated earlier into the `Value` field + +  + +1. Retrigger the last failed run of the `project-audoadd` GitHub action by selecting the run in the [Actions view](https://github.com/MovingBlocks/Terasology/actions/workflows/project-autoadd.yml) and clicking on "Re-run all jobs". diff --git a/docs/Markdown-and-Wiki.md b/docs/Markdown-and-Wiki.md new file mode 100644 index 00000000000..b5b0c9d7319 --- /dev/null +++ b/docs/Markdown-and-Wiki.md @@ -0,0 +1,39 @@ +Markdown and Wiki +=============================== + +The GitHub wiki (and the per-project README) uses the [Markdown](http://daringfireball.net/projects/markdown/syntax) syntax + +In addition to editing the wiki and README via the GitHub interface you can also use IDE plugins to do highlighting with the Markdown formatting and even edit the wiki via Git + +IntelliJ Markdown +--------- + +To set up IntelliJ to support Markdown syntax highlighting and local preview follow these steps: + +* Go to Settings / Plugins +* Browse repositories and search for "Markdown" +* Install the plugin using the button in the toolbar (don't just select the plugin and click Ok - nothing will happen) +* Under Settings / File Types look for "Markdown" (you may have to restart IntelliJ) and make sure `*.md` and `*.markdown` are registered patterns there +* Under Settings / Markdown be sure to enable "hard wraps" to use the right line break format for GitHub +* Restart IntelliJ - you should now have a "Text" and a "Preview" tab in bottom of the main edit area for Markdown files + +Wiki via Git +--------- + +Every wiki hosted on GitHub is itself maintained in Git using [Gollum](https://github.com/github/gollum#readme). There are [instructions](https://github.com/MovingBlocks/Terasology/wiki/_access) available on how to clone a wiki repo + +With a wiki cloned to a local directory you can use IntelliJ (or other editors) to then edit the files locally and do a single push to update a bunch of pages at once, even preview locally. Searching is also made easy. + +An added advantage is that via Git you can enable some advanced features you cannot start with (although you can later edit them) through the web interface, like [sidebars, headers, and footers](https://github.com/github/gollum#sidebar-files) + +We might make a nice automated IntelliJ setup later for wiki editing but it is really super easy to set up - just create a new project in the cloned directory and register the Git root (if IntelliJ doesn't figure that out for you) + +Wiki Automation +--------- + +Since we can interact with the wiki using Git it should be possible to do something like the following: + +* Keep game commands / hot keys / tools etc in definition files that also include help text and examples +* Parse out said information during `develop` builds and update relevant pages in the wiki via Git (separate repo, won't retrigger a build) + * This could also be used by fan-sites to display the information in a different format (raw game info database of sorts) +* Keep a summary in the [README.markdown](https://github.com/MovingBlocks/Terasology#terasology) on the front page that's matched with the `master` branch and update that automatically in the `develop` branch (which is default and thus the front page) diff --git a/docs/Modding-API.md b/docs/Modding-API.md new file mode 100644 index 00000000000..7424c1ae358 --- /dev/null +++ b/docs/Modding-API.md @@ -0,0 +1,28 @@ +Modding API +================= + +Terasology's engine uses a whitelisting approach to expose an API for modules using two primary methods and a rarely needed third one: + +* Classes or packages marked with the `@API` annotation +* Classes or packages in the basic whitelist defined in `ExternalApiWhitelist.java` +* Rarely blocks of code in the engine may be hit in a way requiring use of `AccessController.doPrivileged(...)` - usually module authors do not need to worry about this but once in a while it could explain something quirky. + +This is to both protect the user's system from malicious code (for instance you cannot use `java.io.File` directly) and to better document what is available. If you attempt to use a class not on the whitelist you'll get log message like: + +`Denied access to class (not allowed with this module's permissions): some.package.and.class` + +While modules can themselves use the `@API` annotation to mark interesting code for reuse no special security is attached at this point beyond the engine. Any module can use anything from any other module it declares as a dependency. + +For more information of how the module sandbox works see the [Gestalt Module Sandboxing wiki page](https://github.com/MovingBlocks/gestalt/wiki/Module%20Sandboxing), including how to disable security entirely for prototype work. + +The `ApiScraper.java` class will output a list of all `@API` marked functionality. A sample is visible at https://github.com/MovingBlocks/Terasology/issues/1975#issuecomment-180944901 as of early February 2016 (more enhancements coming) + +As we improve our documentation system expect to eventually see a JavaDoc-like setup highlighting just the modding API related classes. Track status via [#2159](https://github.com/MovingBlocks/Terasology/issues/2159) and [#1975](https://github.com/MovingBlocks/Terasology/issues/1975) + +## See also + +* [Developing Modules](Developing-Modules.md) - how to edit an existing module or create a new one +* [Testing Modules](Testing-Modules.md) - test your module with unit tests and integration tests +* [Module Dependencies](Module-Dependencies.md) - how to deal with modules that depend on another +* [I/O API for Modules](IO-API-for-Modules.md) - reading and writing files from modules +* [Module Security](Module-Security.md) - which threats does the module sandbox protect against, and how? diff --git a/docs/Module-Dependencies.md b/docs/Module-Dependencies.md new file mode 100644 index 00000000000..3d65d795f96 --- /dev/null +++ b/docs/Module-Dependencies.md @@ -0,0 +1,83 @@ +Modules can depend on other modules, just like Java libraries and projects can have dependencies, usually configured via Gradle or Maven. + +For Terasology we've developed a module system later extracted into its [own library "Gestalt Module"](https://github.com/MovingBlocks/gestalt) that our engine project then itself depends on. + +## module.txt + +Rather than a `pom.xml` or Gradle build file our modules use a simple `module.txt` file to hold all configuration for the module including its dependencies. + +For examples simply look at any module in our [module-holding Terasology organization on GitHub](https://github.com/Terasology) + +For more details of how it works you can check out the [Gestalt wiki](https://github.com/MovingBlocks/gestalt/wiki) + + +## Resolving dependencies + +You may end up fetching or creating a module that depends on other modules. Again our Gradle setup makes this super easy to handle! + +If you fetch a module `X` that has a dependency on module `Y` the next execution of any `gradlew` command will automatically fetch a binary copy of module `Y` including in turn any of *its* dependencies (a "transitive" dependency). + +Any binary module dependency will be stored both in your local Gradle cache as well as in `/modules` where the game will use it from at runtime. + +If you later fetch the source code for module `Y` it will automatically take precedence over any old binary copy of `Y` + +You can delete any binary copies of modules at any time then rerun `gradlew` to have them re-fetched. + + +## Using dependencies + +To declare a dependency of your own simply name the module you need in `module.txt` and rerun something like `gradlew idea` - Gradle will handle the rest! + +To define a single dependency to the _Gooey_ module in `0.54.*` you would set the dependencies field to: + +```json + "dependencies" : [ + { + "id" : "Gooey", + "minVersion" : "0.54.0" + } + ], +``` + +If the first major part of the version number is 0 like in the example, then the exclusive maximum version is one minor version higher. Thus the following would also specify a `0.54.*` dependency: + +```json + "dependencies" : [ + { + "id" : "Gooey", + "minVersion" : "0.54.0", + "maxVersion" : "0.55.0" + } + ], +``` + +The above version range includes the version `0.54.0` (but not `0.54.0-SNAPSHOT`) and excludes the version `0.55.0` and `0.55.0-SNAPSHOT`. +Any other `0.54.*` version like `0.54.2` is also included. + +You can include version requirements. Usually this is just whatever is the latest at the time you declare the dependency. + + +All modules which are used directly should be listed as dependency. +Direct use includes dependencies on code, but also prefabs listing components from other modules. + +A dependency can be declared as **optional** by adding `"optional": true` to the dependency information. +An optional module needs to be present at compile-time, but is not required at runtime. + +```json + "dependencies" : [ + { + "id" : "Gooey", + "minVersion" : "0.54.0", + "maxVersion" : "0.55.0", + "optional": true + } + ], +``` + +## Visualizing module dependencies + +To inspect the direct and recursive dependencies of one specific or all locally (as source) available modules, you can use the `groovyw module createDependencyDotFile` command from inside the root folder of the Terasology repository. +Append a module name to only create the dependency file for the direct and recursive dependencies of this module. Please note, the modules that are not available locally or only as .jar files are skipped. + +The resulting dependency file is stored as `dependency.dot`. DOT is a simple graph description language that allows to define nodes and edges. Based on these, a visualization program like GraphViz can create a visual graph. +If you want to use GraphViz for the visualization, you can [download](https://www.graphviz.org/download/) and install it. Afterwards, you can run `dot -Tsvg /dependency.dot > dependency.svg` on the dot file created earlier to create a vector graphic of the dependency graph described in `dependency.dot`. [Other formats](https://graphviz.gitlab.io/_pages/doc/info/output.html) are available as well. diff --git a/docs/Module-Security.md b/docs/Module-Security.md new file mode 100644 index 00000000000..66ae66f19a8 --- /dev/null +++ b/docs/Module-Security.md @@ -0,0 +1,81 @@ +# Testing + +* The [Malicious] module executes its [malicious tests] when its system is initialized. Look for messages from this class in the Terasology log file. +* The [Sample] module provides a `ReallyCrashGameBlock` that attempts [unauthorized use of System.out](https://github.com/Terasology/Sample/blob/develop/src/main/java/org/terasology/sample/crash/CrashGameBlockSystem.java) when you use it. + - use the console to `give ReallyCrashGameBlock` + - place the block on the ground + - hit the `Use` key + +[Malicious]: https://github.com/Terasology/Malicious +[malicious tests]: https://github.com/Terasology/Malicious/blob/develop/src/main/java/org/terasology/maliciousUsageTests/MaliciousTestSystem.java +[Sample]: https://github.com/Terasology/Sample + + +# Threat Models + +## Threats from local execution of untrusted modules + +### Accessing a local resource + +For example: +* a local file +* capture your desktop (outside the game window) +* snoop on local devices (keyboard, webcam, USB drives) + + +### Accessing your local network +* smartphones and other computers +* printers and other Internet-connected Things + + +### Exfiltration and Exploitation of Remote Networks +* uploading data to a third-party server +* using network resources to attack a remote target + +⚠ A module _will_ send data to the game server you are connected to. The thing to prevent is sending information to a third party without the consent of either client or server. + + +## Threats from network input from untrusted clients + +The game creates new objects and executes methods on them in response to network input. An attacker may attempt to craft a message that tricks the server in to executing an unsafe method. + + +# Security Mechanisms + +Terasology relies on [Gestalt Module Sandboxing](https://github.com/MovingBlocks/gestalt/wiki/Module%20Sandboxing) to protect from these risks of running untrusted JVM code. However, it's up to the application to make sure the sandbox is configured and applied correctly. + +* [o.t.engine.core.module.ExternalApiWhitelist](https://github.com/MovingBlocks/Terasology/blob/develop/engine/src/main/java/org/terasology/engine/core/module/ExternalApiWhitelist.java) defines a hardcoded list of allowable packages and classes. + +## ClassLoaders + +* `ModuleManager.setupSandbox` configures a PermissionProviderFactory with modules and the allowable packages and classes. +* `ModuleManager.loadEnvironment` constructs a gestalt.module.ModuleEnvironment with that PermissionProviderFactory. + + +## Java Security Manager + +`o.t.engine.core.ModuleManager.setupSandbox` installs the gestalt ModuleSecurityPolicy and ModuleSecurityManager. + +The restrictions of ModuleSecurityPolicy apply to classes which were loaded using a ModuleClassLoader. + +⚠ This API is proposed for removal from a future version of the JDK ([JEP 411]). If it's first deprecated in JDK 17, it will be quite a while yet before it's removed entirely, but eventually will come a time when we'll want the features of a new JDK and the Security Manager is no longer available. + +[JEP 411]: https://openjdk.java.net/jeps/411 "JEP 411: Deprecate the Security Manager for Removal" + + +## Type Registry + +* The [nui-reflect TypeRegistry](https://github.com/MovingBlocks/TeraNUI/blob/ff5ec35083520d8bb986f410fda482ea6bb5ca93/nui-reflect/src/main/java/org/terasology/reflection/TypeRegistry.java#L73) uses lists of allowable classes and packages to guard against ⎵⎵⎵⎵⎵. +* an `o.t.persistence.typeHandling.TypeHandlerLibrary` makes use of both a nui-reflect TypeRegistry _and_ a gestalt ModuleEnvironment. + + +# Related: +* [Modding API](Modding-API.md) +* [IO API for Modules](IO-API-for-Modules.md) for local persistent storage + + +# Threats not addressed + +* local denial of service attack (excessive CPU and RAM consumption) +* exploiting local computing resources (crypto mining) +* …? diff --git a/docs/Module.txt.md b/docs/Module.txt.md new file mode 100644 index 00000000000..ff207f155d3 --- /dev/null +++ b/docs/Module.txt.md @@ -0,0 +1,38 @@ +# Module.txt + +## Contents + +* _id_ - Machine-readable name of the module. Used by the terasology engine and other modules to refer to the module. +* _version_ - Version of the module. See [Module Versioning](Release-Modules.md#versioning) +* _displayName_ - The name of the module isplayed to end-users +* _description_ - Human-readable description of the module. +* _dependencies_ - List of ids and minVersions of modules needed for this module to work. See [Module-Dependencies](Module-Dependencies.md) +* _defaultWorldGenerator_ - The default world generator to use for this module. + +### Ways to categorize your module: + +* _serverSideOnly_ - only used on servers +* _isGameplay_ - defines a game type/mode (mod pack) that may depend on a large number of modules and forces a particular style of play. Unlikely to work well with other gameplay modules. Example: WoodAndStone, LightAndShadow +* _isAugmentation_ - some sort of plug and play content that can be enabled and seen/played, but doesn't force particular gameplay. Could work in combination with a gameplay module. Example: NightTerrors* isAsset - plain art / passive content module, possibly with basic block/model definitions. Example: LASR, Minerals, Soils +* _isWorld_ - provides world generation features. Example: AnotherWorld +* _isLibrary_ - active content for use by other modules. Cannot be used by itself. Typically Component Systems. Example: BlockNetwork +* _isSpecial_ - Special-purpose modules. Core, Sample, Malicious + +## Example + + + { + "id" : "CoreSampleGameplay", + "version" : "2.0.0-SNAPSHOT", + "displayName" : "Core Gameplay", + "description" : "Minimal gameplay template. Little content but a few starting items.", + "dependencies" : [ + {"id": "Core", "minVersion": "2.0.0"} + ], + "isGameplay" : "true", + "defaultWorldGenerator" : "Core:FacetedPerlin" + } + +## More information + +[Gestalt Modules](https://github.com/MovingBlocks/gestalt/wiki/Modules) - In-depth discussion of Modules (non-Terasology-specific) \ No newline at end of file diff --git a/docs/Multi-Repo-Workspace.md b/docs/Multi-Repo-Workspace.md new file mode 100644 index 00000000000..af13c7441c2 --- /dev/null +++ b/docs/Multi-Repo-Workspace.md @@ -0,0 +1,31 @@ +A concept that is especially confusing to newcomers that do not have a lot of Git experience is Terasology's multi-repository workspace. +In the following, we try to shed some light on what "multi-repository workspace" means in the first place and how it affects your development workflow. + +## The Workspace Root + +Your Terasology workspace is created by cloning our [engine repository](https://github.com/MovingBlocks/Terasology) (see the first step in the [Contributor Quick Start](https://github.com/MovingBlocks/Terasology/wiki/Contributor-Quick-Start#set-up-your-terasology-development-workspace)). The directory this creates will be considered your workspace and whenever you'll be in this directory, you'll be in your workspace root. + +The workspace root content structure equals what you can see in the engine repository. You'll find the same directories and root-level files in your workspace root that you will also find in the engine repository. + +## The `modules` sub-directory + +Directly after cloning the engine repository, you could enter the `modules` sub-directory and notice that it does not have any sub-directories itself. However, after following the Contributor Quick Start further, you'll eventually notice that new directories pop up in your `modules` subdirectory. These directories are the local representation of modules. Whenever you build and start Terasology from source, the modules you can see listed in the Advanced Game Setup are the once locally available in your `modules` sub-directory. + +These module directories typically show up as soon as you run either of the following commands: +* `groovyw module init `, e.g. `groovyw module init iota` +* `groovyw module recurse `, e.g. `groovyw module recurse JoshariasSurvival` +* `groovyw module get `, e.g. `groovyw module get Health` + +What these `groovyw module` commands do in the background is clone a single (in case of `get`) or multiple (in case of `init` and `recurse`) module repositories into your `modules` sub-directory. Each directory this creates in your `modules` sub-directory will contain the exact contents the respective module repository in the ["Terasology" GitHub organization](https://github.com/Terasology) does. + + + +The same is true for the `libraries` sub-directory, only with library repositories like [`gestalt`](https://github.com/MovingBlocks/gestalt) or [`TeraNui`](https://github.com/MovingBlocks/TeraNUI) residing in the [`MovingBlocks` GitHub organization](https://github.com/MovingBlocks) instead. However, in your basic Terasology contributions, you'll rarely have to care about this. + +## What this means for your development workflow + +Whenever you are in your workspace root or any of its sub-directories and execute `git` commands (e.g. `git switch`, `git commit`, `git push`), these commands will target the upstream engine repository which usually is either the original [Terasology engine repository](https://github.com/MovingBlocks/Terasology) or your fork of it. **This is true for all sub-directories except the sub-directories of `modules` and `libraries`**. + +Whenever you are in a sub-directory of `modules` and `libraries`, the `git` commands you execute will target the respective upstream module or library repository. For instance, when you're in the `modules/Health` sub-directory, your `git` commands will either target the original [`Health` repository](https://github.com/Terasology/Health) or your fork of it. + + diff --git a/docs/Outreach.md b/docs/Outreach.md new file mode 100644 index 00000000000..fdb703cc9d9 --- /dev/null +++ b/docs/Outreach.md @@ -0,0 +1,30 @@ +## Writing Blog Posts + +If you want to write a blog post for the [Terasology Website](https://terasology.org/) to highlight the latest contributions or community events, you can do so as follows: + +1. Set yourself up for contributing to our [ModuleSite repo](https://github.com/MovingBlocks/ModuleSite) + + _You can use any contribution path you like. For example, you could fork and clone it, use the GitHub UI, or Codespaces._ +1. Add a new directory in the [`blog` subdir](https://github.com/MovingBlocks/ModuleSite/tree/master/blog) + + _The directory name should comply with the following pattern: `YYYY-MM-DD- `, e.g. `2023-01-16-my-fancy-blogpost`_ +1. Optional: In your blog post directory, add a cover image (ideally in `.jpg` format) +1. In your blog post directory, create a file named `index.md` + + _The metadata section should be at the top of your `index.md`:_ + ``` + --- + posttype: "blog" + title: <title> + cover: "./<cover-image-name>.jpg" + description: <summary> + author: <your-nickname> + date: "YYYY-MM-DD" + tags: [<tag-list>] + --- + ``` + _Valid tags are "TeraSaturday", "TeraSpotlight", "GSoC", "Update", "Project". If you are uncertain which one to use or want to propose a new one, ask the `@Publicity` folks in our #outreach channel on Discord._ +1. Add your blog post content in markdown below the metadata section. +1. Open a PR with your changes. + +**Note:** _Please check copyright of any external images you want to use, download them and commit them as part of your PR._ diff --git a/docs/Play-Test-Setup.md b/docs/Play-Test-Setup.md new file mode 100644 index 00000000000..18aaa2ffd2a --- /dev/null +++ b/docs/Play-Test-Setup.md @@ -0,0 +1,104 @@ +We try to run a monthly play test session and may also run some ad hoc whenever there's a reason to. This page covers the logistics in setting up the test server. + +- [Overview](#overview) +- [Create the server](#create-the-server) +- [Expose the server](#expose-the-server) +- [Upload build](#upload-build) + - [Unusual builds](#unusual-builds) +- [Adjust configuration](#adjust-configuration) +- [Start server](#start-server) +- [Adjust Log Output](#adjust-log-output) + +## Overview + +The involved phases will usually go like so: + +* Create the server +* Expose the server (update DNS) +* Upload the desired build + * Getting a desired build +* Adjust configuration +* Start server + +Then we may rinse & repeat as necessary during a single play test to either adjust config or possible update to a newer build yet. In the end consider destroying the server again to clean up + +## Create the server + +At present we use DigitalOcean to host virtual machines, called droplets. There is a stored snapshot we can create a new droplet from to have everything needed for Terasology ready. + +With access acquired to our DO account (ask any logistically minded contributor that looks like they might know what they're doing): + +* Log in to [DO](https://cloud.digitalocean.com/projects/ef80fed5-434c-450c-848e-f76a6a38667a/resources?i=dae9f4) and make sure you're on the "Terasology" project +* Go to "Create Droplets" +* Go to the "Snapshots" tab +* Pick the `testserver.terasology.net...` entry +* Click the "Select all" checkbox in the Authentication section to give all keys access +* Adjust the hostname to just say "testserver.terasology.net" then press "Create Droplet"! + +Wait for the droplet to appear in the list, and consider copying its IP. Occasionally we've enabled IPv6 as well but not sure we ever use it or have even tested it. If you need it there should be a checkbox to enable it as well to check + +## Expose the server + +* With the working server up go to Networking - Domains - `terasology.net` +* Find the existing `A` entry for `testserver.terasology.net` and click More -> Edit Record +* Paste in the IP, or just click in the box a time or two and let auto-complete show you all the droplets then pick the right one +* Do the same for the `AAAA` record if you want to enable IPv6 (will only work if you added IPv6 networking during droplet creation) + +Consider testing locally with `ipconfig -flushdns` or comparable if needed, then ping `testserver.terasology.net` and make sure the IP looks right + +## Upload build + +Use a tool like WinSCP or any other SSH / file transfer tool of your choice + +* Make sure you have the desired build available locally and extracted (see [Release: Omega](Release-Omega.md) for instructions how to create a release) +* Open an `ssh` session for user "root" on the server and go to `/opt/terasology` if not already there +* `rm -rf server libs modules` to reset current state +* Copy the `libs` and `modules` from your local build to the server + +That is usually enough. The executables change exceedingly rarely, as do the natives - but they do change every once in a while! That's often when it is a good idea to make a whole new snapshot so you again only need to worry about `libs` and `modules` to get back up to date. + + +### Unusual builds + +Occasionally we might need to do unusual things for builds + +* If the server crashes with an error sounding like natives are out of date simply replace `natives/` on the server with the same from a local Omega zip +* If you need to test a PR use the attached zip on a PR build from http://jenkins.terasology.io/teraorg/job/Terasology/job/engine/view/change-requests/ to update solely `libs/` on the server. Either leave the modules in place (if testing engine) or replace individual module jars in `modules/` + * Module jars should be attached to their builds under http://jenkins.terasology.io/teraorg/job/Terasology/job/Modules and their `develop` branches are also [published to Artifactory](http://artifactory.terasology.org/artifactory/webapp/#/artifacts/browse/tree/General/terasology-snapshot-local/org/terasology/modules) during those builds + * If you only see weird artifacts attached in Jenkins then simply rebuild the target branch/PR for the module to get new artifacts (changed 2020-11-20) - Artifactory should always have latest and historical module jars, but generally only for `develop` branches + + +## Adjust configuration + +With a remote session open the `override.cfg` file at `/opt/terasology` and adjust the list of active modules and the target world. Easy enough. Typical modules to _usually_ enable + +* CheatsForAll (to ease console cheating for connected players) +* ChrisVolume1OST because pretty music (and maybe even ChrisVolume2OST!) +* HumanoidCharacters so you can see other players as more than a floating cube - can be situational (don't use for Light & Shadow, for instance) + +Likely not needed but if for some reason you need to vary the launch arguments you may need to edit one of the executables (memory settings, server facade ..) + +## Start server + +In your `ssh` session: + +* `screen` to get a detachable sub-shell or whatever that may be called :-) +* `run_linux.sh` +* `CTRL-A` then `D` to detach from the session (so the server doesn't die if you disconnect your `ssh`) +* To reattach SSH back in then use `screen -r` (if there are multiple screens instructions will be logged) + +After the play test is over you may or may not want to terminate the droplet server, based on who might need it in the near future. Does cost money to keep it running. + +## Adjust Log Output + +To adjust the logging configuration for the server update the `logback.xml` contained in `libs/Terasology.jar`. +To patch the JAR file the `jar` tool is required (part of the JDK). + +> If it is not installed on the server droplet, you may need to download `libs/Terasology.jar` and perform the steps locally. + +Perform the following steps to extract, patch, and update the Logback configuration file: + +* `jar xf Terasology.jar logback.xml` to extract the logback configuration from the JAR +* `vi logback.xml` (or any other text editor) to adjust the logback configuration (see [The logback manual](https://logback.qos.ch/manual/)) +* `jar uf Terasology.jar logback.xml` to patch the JAR file with the updated configuration +* (`rm logback.xml` to clean up the extract configuration file as it is no longer needed) diff --git a/docs/Project-Overview.md b/docs/Project-Overview.md new file mode 100644 index 00000000000..42161b58c89 --- /dev/null +++ b/docs/Project-Overview.md @@ -0,0 +1,58 @@ +This is a overview of all the involved sites, GitHub repositories and related projects that are involved with Terasology + +Sites +--------- + +Our online presence covers: + +* [Portal / forum](http://forum.terasology.org) - main site for announcements and discussion +* [Meta Server](http://meta.terasology.org) - shows a list of game servers, modules, and so on. Can be used via API and is used as such by the game and launcher. +* [Splash Site](http://terasology.org) - a small GitHub Page (hosted [here](https://github.com/MovingBlocks/movingblocks.github.com) to intro the game, play via applet, or even run the soundtrack (top left - Flash) + * Note: Both applets and flash are aging as technologies and may not work in some browsers due to support and security. Goal is to eventually replace with Java Webstart and HTML5. +* Social networks: [Reddit](https://www.reddit.com/r/Terasology) | [Facebook](https://www.facebook.com/Terasology) | [Twitter](https://twitter.com/Terasology) | [G+](https://plus.google.com/b/103835217961917018533/103835217961917018533/posts) + +Primary Repositories +--------- + +The central components of Terasology live under two GitHub Organizations. The ones needed to run the base game are listed below. + +See [Codebase Structure](Codebase-Structure.md) for more details on each piece + +* [MovingBlocks](https://github.com/MovingBlocks) - this organization primarily contains the engine itself plus facades. It also holds some library projects - more below + * [Engine](https://github.com/MovingBlocks/Terasology): The beating heart of the game. Also contains the PC Facade (the standard application) and the Core Module, as they're required for the base game to run normally +* [Terasology](https://github.com/Terasology) - this organization is entirely meant for hosting content modules. These come in two flavors + * Root repos: Modules that follow the full Contributor Guidelines and may be maintained to some degree by the official community + * Fork repos: Modules hosted by modders elsewhere on GitHub that follow the Modder Guidelines and are eligible for inclusion in official distributions and the launcher + +Libraries +--------- + +We've created some library projects while working on Terasology that are used in-game + +* [TeraBullet](https://github.com/MovingBlocks/TeraBullet) - Offers some voxel-world integrations with [JBullet](http://jbullet.advel.cz) +* [TeraOVR](https://github.com/MovingBlocks/TeraOVR) - Wrapper for the [Oculus Rift](http://www.oculusvr.com) SDK +* [Jitter](https://github.com/openleap/jitter) - Utility framework for the [Leap Motion](https://www.leapmotion.com/) (hosted under the [OpenLeap](https://github.com/openleap) organization) + +Other projects +--------- + +These are indirect parts of the project, such as our supporting site work and launcher + +* [Launcher](https://github.com/MovingBlocks/TerasologyLauncher) - the best way to run the game. Allows easy auto-updating and managing different versions of the game +* [Applet](https://github.com/MovingBlocks/FacadeApplet) - the Facade running the applet version of the game you can [play in your browser](http://terasology.org/#play) +* [Splash Site](https://github.com/MovingBlocks/movingblocks.github.com) - our GitHub-hosted front-end site at http://terasology.org offering a few quick links and what not - just in case our primary site gets slammed or something :-) +* [Gooey](https://github.com/MovingBlocks/Gooey) - our handy little [Hubot](http://hubot.github.com/)-based IRC bot offering witty banter and useful functionality like auto-creating GitHub repos. When he feels like it, anyway! +* [TeraMisc](https://github.com/MovingBlocks/TeraMisc) - a repository for miscellaneous stuff that doesn't really fit anywhere else. Like raw model files, assorted utility scripts, stuff for our [XenForo](http://xenforo.com) site ([forum/portal](http://forum.movingblocks.net)) + +External projects +--------- + +These are noteworthy external projects we use + +* [LWJGL](http://lwjgl.org) - foundation for graphics, sound, and input +* [Gradle-Git](https://github.com/ajoberstar/gradle-git) - makes Gradle even more magical by adding Git tasks +* [Jenkins CI](http://jenkins-ci.org) - continuous integration tool, builds our stuff at http://jenkins.movingblocks.net +* [Artifactory](http://www.jfrog.com/home/v_artifactory_opensource_overview) - repository manager, holds our builds and assorted library files, at http://artifactory.movingblocks.net +* [XenForo](http://xenforo.com) - our portal/forum site at http://forum.movingblocks.net + + diff --git a/docs/Randomness-and-Noise.md b/docs/Randomness-and-Noise.md new file mode 100644 index 00000000000..034efce8b5e --- /dev/null +++ b/docs/Randomness-and-Noise.md @@ -0,0 +1,24 @@ +# Randomness and Noise + +Random numbers play a major role in procedural terrain generation and many other dynamically created content in the game. There are different random number generators and different types of noise. + +## Random Numbers + +There are two implementations of the `Random` interface: `FastRandom` and `MersenneRandom`. As you might expect, the first one is rather simplistic, which makes it very fast. In some cases, the quality is not sufficient though and we recommend the implementation that is based on the Mersenne prime number twister. It is very close to *real* noise, but more expensive to compute. + +**Rule of thumb:** Use `MersenneRandom` when looking at very small value ranges (e.g. floats between 0 and 0.000001 or boolean values), FastRandom otherwise. + + +## Noise + +Noise generators are similar to random number generators, but provide a deterministic value per coordinate in space. + +The `PerlinNoise` and `SimplexNoise` classes assign random gradient in a regular grid (Perlin uses squares/cubes, Simplex uses triangles/tetrahedrons) and interpolate in between. Simplex is a bit faster than Perlin, in particular for higher dimensions at comparable noise quality. Noise is isotropic (looks the same independent from direction or position). + +The `BrownianNoise` class integrates values from other noise implementations. This allows for adjustment of noise frequencies. For example, different layers of Perlin noise can be put on top of each other at different spatial scales and at different amplitudes. This gives the prominent Perlin noise textures. + +The `FastNoise` class is a bit different as it works on discrete numbers. This is good enough for per-block noise values. It is about 2x faster than SimplexNoise and 5x faster than PerlinNoise. Noise values repeat after 256, i.e. noise(256) is equal to noise(0). + +**Rule of thumb:** Use `SimplexNoise` whenever possible. Noise that is required per block can also be computed using `FastNoise`. + + \ No newline at end of file diff --git a/docs/Record-and-Replay-Code-Details.md b/docs/Record-and-Replay-Code-Details.md new file mode 100644 index 00000000000..149bb3ab9eb --- /dev/null +++ b/docs/Record-and-Replay-Code-Details.md @@ -0,0 +1,27 @@ +# Record and Replay Code Details + +## Recording and Replay workflow + +For more details about the workflow, check [RecordAndReplayCurrentStatus](https://github.com/MovingBlocks/Terasology/blob/develop/engine/src/main/java/org/terasology/recording/RecordAndReplayCurrentStatus.java)'s Javadoc. + +### Recording a Game + + + +### Replaying a Recording + + + +## Record and Replay classes in the Context + +### Added on `TerasologyEngine` + +- CharacterStateEventPositionMap +- DirectionAndOriginPosRecorderList +- RecordAndReplayCurrentStatus +- RecordAndReplayUtils + +### Added on `EntitySystemSetupUtil` + +- EventSystem (`EventSystemReplayImpl` if it's a Replay) +- RecordAndReplaySerializer diff --git a/docs/Release-Modules.md b/docs/Release-Modules.md new file mode 100644 index 00000000000..3b5bd300126 --- /dev/null +++ b/docs/Release-Modules.md @@ -0,0 +1,109 @@ +This is a guide for maintainers to explain how the [CI/CD pipeline](http://jenkins.terasology.io/teraorg/job/Terasology/job/Modules/) for modules in the [Terasology :octocat: ](https://github.com/Tearsology) organization works, and what steps should be taken to release a new version of a module. + +## CI/CD Setup + +Modules in the [Terasology :octocat: ](https://github.com/Tearsology) organization follow a **single-branch setup** with `develop`. Commits to this branch are automatically built and published to our [Artifactory], either as a release or as snapshots, depending on the version specified in `module.txt`. + +### Branches + +- **`develop`** • central place for _active development_ + > All active development happens on this branch. PRs SHOULD be directed against the `develop` branch. This branch is to be considered **unstable** and may hold experimental features and/or even fail compilation during active development. During development, a module MAY depend on unreleased modules. + > In the current state, modules only evolve forward and are not tied to a support or maintenance window. There is only a single track for releases (e.g., no bug fixes or patches on older releases). + > Releases of modules SHOULD be tagged commits directly in the history of the main `develop` branch. Release commits SHOULD NOT contain dependencies to unreleased modules (e.g., snapshot releases). + +PRs against modules are built and checked by the pipeline, but not published to [Artifactory]. + +### Versioning + +Modules SHOULD be versioned according to [Semantic Versioning 2.0.0 (SemVer)](https://semver.org/). The module version is defined in the _version_ entry in `module.txt`. + +Builds from `develop` directly use the version as defined in `module.txt`. Note, that there is only one snapshot build for a specific base version (e.g., `1.2.3-SNAPSHOT`) and subsequent snapshot builds will just override the artifact (read more about [What exactly is a Maven Snapshot and why do we need it?](https://stackoverflow.com/questions/5901378/what-exactly-is-a-maven-snapshot-and-why-do-we-need-it) on StackOverflow). +If the module was already released with a specific version (e.g., there was no version bump after the last release), publishing it to [Artifactory] again will fail and only the existing release will be available. + +## Module Release Process + +Releasing a module involves a couple of manual steps bump the version accordingly. + +1. **Decide on release version** • Make sure `develop` has the intended next version in `module.txt` + + _The version number MUST be a higher SemVer than the last release commit. The version bump SHOULD follow SemVer specifications, e.g., increase the major version for breaking changes, or do a patch release if only internal behavior was fixed. You can [compare commits or branches](https://docs.github.com/en/github/committing-changes-to-your-project/comparing-commits) on Github easily to get an overview of the changes:_ + ``` + https://github.com/Terasology/{{module}}/compare/{{latest_release_tag}}...develop + ``` + + _Make sure that your local state of `develop` is up to date:_ + + ```sh + git checkout develop + git pull + ``` + + _Change the version by updating it in `module.txt` and commit the change with the following message:_ + + > `release: version {{version}}` + +1. **Push `develop` to upstream** • This triggers the actual release! + + ```sh + git push origin develop + ``` + + Until we have automatic tagging or a tag-based release process it is recommended to manually [create and push an annotated tag][git-tag] for the respective version on `master`. For a module release v1.2.3 the tag process is: + + ```sh + git tag -a v1.2.3 -m "Release version 1.2.3" + git push origin v1.2.3 + ``` + +1. **Prepare for next release** • Bump version + + _We have to increase the version number on `develop` to be able to get pre-release `-SNAPSHOT` builds for any progress on the development branch. Therefore, the version number MUST be a higher SemVer than the version just released on `master`. This will typically be a **minor** version bump. To do this, just update the version in `module.txt` and commit the change with the following message:_ + + > `chore: prepare snapshot builds for {{version}}` + + _Finally, push the preparation commit and you are done!_ + + ```sh + git push origin develop + ``` + +## How Publishing Works + +The builds steps for modules are defined in the [Jenkinsfile](https://github.com/MovingBlocks/ModuleJteConfig/blob/master/Jenkinsfile) of the [ModuleJteConfig repository](https://github.com/MovingBlocks/ModuleJteConfig), which are similar to the engine steps with the [JTE](https://plugins.jenkins.io/templating-engine/) repository just being a way to apply that build setup across _all_ module repos, without having to maintain individual files. + +The major difference is that much like not having their own `Jenkinsfile` module repos also skip all the other build-related files, in favor of having Jenkins copy them in at build time (a sort of "build harness"). Modules are built in a standalone directory (no engine source), which has some pros and cons. You can replicate a standalone module build locally by copying the module to its own home then copying in the files indicated in the `Jenkinsfile` (Gradle stuff and such) + +In a regular engine workspace locally our utility scripting simply drops in a template `build.gradle` to make the module part of the project tree, then the Gradle files elsewhere in the workspace work normally. + +At the conclusion of a Gradle build if the publish step is invoked Gradle will try to publish binaries to a given target _artifact repository_ in Artifactory, so a full release goes to a release repo and a snapshot build goes to a snapshot repo. Jenkins defines a credential to grant access to do the publish against Artifactory, which is loaded in the `Jenkinsfile` + +## Publish an Artifact Manually or for Testing + +You can do a publish of binaries from a local system without Jenkins being involved at all, as well as redirect where the published artifacts go if necessary. + +With a local _engine_ workspace you should get a template `gradle.properties` placed in the root directory with a series of related fields. + +``` +# Alternative resolution repo to use - this can be used to ignore "live" artifacts and only accept experimental ones. +# alternativeResolutionRepo=http://artifactory.terasology.org/artifactory/virtual-nanoware-and-remote + +# Where to publish artifacts, if not to the default snapshot/release repos +# Publishing a snapshot to a release-only repo will get an intended but quirky HTTP 409 Conflict error as of Nov 2014 +# publishRepo=nanoware-snapshot-local + +# Credentials for publishing to Artifactory. Good for local testing +# mavenUser= +# mavenPass= +``` + +If set, these properties will determine how Gradle resolves artifacts, where binaries are published, and what credential to use. If you're just trying to publish from a local workspace (engine or module) you should simply acquire and fill in the username and password fields, leaving the rest still commented out. The `gradlew publish` task should then succeed. + +If trying to solely test the publishing process _itself_ you can redirect where artifacts go by uncommenting the `publishRepo` property, in this case that would publish to a Nanoware (test) repo instead of the Terasology (live) repo, which means the published binaries will **not** be resolved with normal config. To test if such binaries do resolve you can uncomment the `alternativeResolutionRepo` property, keeping in mind that most things aren't published there in the first place so other dependencies may become unavailable. + +There is a whole separate line of [Nanoware](http://jenkins.terasology.io/teraorg/job/Nanoware/) build jobs available in Jenkins that use the same two properties (defined as environment variables on the Nanoware _Folder_ object in Jenkins) so you can test multi-stage builds that rely on released artifacts from earlier phases, all without ever exposing any released artifacts to the "live" environment. + +<!-- References --> + +[artifactory]: http://artifactory.terasology.org +[git-tag]: https://www.atlassian.com/git/tutorials/inspecting-a-repository/git-tag +[linear-git-history]: https://www.bitsnbites.eu/a-tidy-linear-git-history/ diff --git a/docs/Release-Omega.md b/docs/Release-Omega.md new file mode 100644 index 00000000000..4cd66fa6d12 --- /dev/null +++ b/docs/Release-Omega.md @@ -0,0 +1,109 @@ +This is a guide for maintainers to explain how the [CI/CD pipeline](http://jenkins.terasology.io/teraorg/job/Terasology/job/Omega/) for the Omega game bundle of [Terasology :octocat: ](https://github.com/MovingBlocks/Terasology) works, and what steps should be taken to release a new (stable) version of the game. + +# CI/CD Setup + +The Terasology engine repository at [MovingBlocks/Terasology :octocat:](https://github.com/MovingBlocks/Terasology) follows a **two-branch setup** with `master` and `develop`. +Commits to these branches are automatically built and published to our [Artifactory], either as a release or as snapshots. +For more details, see our [Build-Setup](Build-Setup.md). + +## Branches + +- **`master`** • the _release_ branch + > In the current state, the engine only evolves forward and is not tied to a support or maintenance window. There is only a single track for releases (e.g., no bug fixes or patches on older releases). The release branch is infrequently updated with the latest state from the develop branch to form a new release. Release commits SHOULD NOT contain dependencies to unreleased modules (e.g., snapshot releases). +- **`develop`** • central place for _active development_ + > All active development happens on this branch. PRs SHOULD be directed against the `develop` branch. This branch is to be considered **unstable** and may hold experimental features and/or even fail compilation during active development. During development, the engine MAY depend on unreleased dependencies (e.g., SNAPSHOTs of libraries). + +PRs against the engine are built and checked by the pipeline, but not published to [Artifactory]. + +## Versioning + +The engine SHOULD be versioned according to [Semantic Versioning 2.0.0 (SemVer)](https://semver.org/). The engine version is defined in multiple places. Best to search for the current version number to find them - for instance one in `engine/`, one in `engine-tests/`. + +> _State of August 8, 2021: The engine version is defined in the following files:_ +> * _[Engine `module.txt`](https://github.com/MovingBlocks/Terasology/blob/develop/engine/src/main/resources/org/terasology/engine/module.txt)_ +> * _[Engine Tests `module.txt`](https://github.com/MovingBlocks/Terasology/blob/develop/engine-tests/src/main/resources/org/terasology/unittest/module.txt)_ +> +> _Please also search for other occurrences in case this has changed since._ + +In addition, the _maturity level_ for the overall project is tracked in `templates/version.txt`. It lists the maturity, e.g., "alpha", and has an _increment_ for the release. When we release the engine and bump to a new snapshot version the increment should also be bumped (for instance, bump from "alpha-18" to "alpha-19"). + +The version on `develop` MUST be appended with `-SNAPSHOT` for snapshot builds. Note, that there is only one snapshot build for a specific base version (e.g., `1.2.3-SNAPSHOT`) and subsequent snapshot builds will just override the artifact (read more about [What exactly is a Maven Snapshot and why do we need it?](https://stackoverflow.com/questions/5901378/what-exactly-is-a-maven-snapshot-and-why-do-we-need-it) on StackOverflow). +If the engine was already released with that version, publishing it to [Artifactory] again will fail and only the existing release will be available. + +# Omega Release Process + +**Note:** Building the Omega release bundle for Terasology will always include the latest versions of modules available at the point in time the build is triggered. This means that re-triggering an Omega build might result in a different result when modules have been built in the meantime, e.g., because of merging changes. + +## Preview Builds + +With every commit to the main branch of [MovingBlocks/Terasology](https://github.com/MovingBlocks/Terasology) both [an engine build](http://jenkins.terasology.io/teraorg/job/Terasology/job/engine/job/develop/) and, on success, [an Omega build](http://jenkins.terasology.io/teraorg/job/Terasology/job/Omega/job/develop/) are automatically triggered. + +A manual preview build can be triggered on demand by just triggering the build job in Jenkins. This might be required to get a preview build with module changes even if the engine did not change. + +* Log in at http://jenkins.terasology.io - uses GitHub OAuth +* Run the build for [teraorg/Terasology/Omega/develop](http://jenkins.terasology.io/teraorg/job/Terasology/job/Omega/job/develop/) +* After about 10-15 minutes the build should be finished with a new game release ([latest successful build](http://jenkins.terasology.io/teraorg/job/Terasology/job/Omega/job/develop/lastSuccessfulBuild/)) + +## (Stable) Release Builds + +Releasing the engine (and with it, an Omega bundle) involves a couple of manual steps to merge changes into the _release branch_ and prepare the development branch for further contributions. + +1. **Decide on release version** • Make sure `develop` has the intended next version in the respective files (see above): + + _The version number MUST be a higher SemVer than the current version of `master`. The version bump SHOULD follow SemVer specifications, e.g., increase the major version for breaking changes, or do a patch release if only internal behavior was fixed. You can [compare commits or branches](https://docs.github.com/en/github/committing-changes-to-your-project/comparing-commits) on Github easily like this:_ + ``` + https://github.com/MovingBlocks/Terasology/compare/master...develop + ``` + + _Make sure that your local state of `develop` is up to date:_ + + ```sh + git checkout develop + git pull + ``` + + _If the version needs to be changed, just update it and commit the change with the following message:_ + + > `chore: prepare release {{version}}` + +1. **Merge `develop` into `master`** • This triggers the actual release! + + _The merge SHOULD happen with a **merge commit** to be able to identify when we merged to master, i.e., which commit is a release commit. + The final commit is done with `--no-ff` to prevent fast-forward merges and create a merge commit. + Use the following commit message for this commit:_ + > `release: version {{version}}` + + + ```sh + git checkout master + git pull + git merge --no-ff develop + git push origin master + ``` + + Until we have automatic tagging or a tag-based release process it is recommended to manually [create and push an annotated tag][git-tag] for the respective version on `master`. For a release v1.2.3 the tag process is: + + ```sh + git tag -a v1.2.3 -m "Release version 1.2.3" + git push origin v1.2.3 + ``` + +1. **Prepare for next release** • Reset `develop` and bump version + + > 🚧 Is resetting `develop` really necessary ❓ + + _After creating a merge commit to merge the develop branch into the release branch now reset `develop` to the latest state of `master` - both branches are even and we can start fresh with the next development goals. To reset the development branch, run the following command that pushes the state of `master` to `develop`._ + + ```sh + git push origin master:develop + ``` + + _Finally, we have to increase the version number on `develop` to be able to get pre-release `-SNAPSHOT` builds for any progress on the development branch. Therefore, the version number MUST be a higher SemVer than the version just released on `master`. This will typically be a **minor** version bump. Don't forget to bump the version in `templates/version.txt` as well. Commit the change with the following message:_ + + > `chore: prepare snapshot builds for {{version}}` + + +<!-- References --> + +[artifactory]: http://artifactory.terasology.org +[git-tag]: https://www.atlassian.com/git/tutorials/inspecting-a-repository/git-tag diff --git a/docs/Renderer.md b/docs/Renderer.md new file mode 100644 index 00000000000..866d3febe64 --- /dev/null +++ b/docs/Renderer.md @@ -0,0 +1,24 @@ +## Introduction +At this stage this page is mostly a placeholder for renderer-related documentation that will be written. + +The renderer has undergone major refactoring over the 2015-2017 period, and is now _approaching_ the stage where A) we can map its components and what it does (see diagrams below for a starter) and B) we will be able to provide an API for modules developers to use, to improve, expand or replace the current renderer functionality. + +We expect to write documentation on these matters as soon as we have sufficiently stabilized the API and its underlying code. + +## Early Diagrams +These diagrams are the very first to have been created since the renderer was structured enough for us to map it. They provide an early understanding of the current state of the renderer. + +* Render DAG - Nodes-only: https://sketchboard.me/XAE5jbOHEtPN#/ (easier version to follow, for an overview) +* Render DAG - Full: https://sketchboard.me/nAE1f4q2pDpd#/ (complete version, more details, more intricate) + +## Debugging Rendering with RenderDoc + +For easier debugging of rendering issues, you can use [RenderDoc](https://renderdoc.org/). +Please refer to RenderDoc's [Quick Start Documentation](https://renderdoc.org/docs/getting_started/quick_start.html) for the basic setup. + +The recommended configuration for launching an application to capture a frame is the following: + + + +When running Terasology from IntelliJ, this should display the java command used by IntelliJ to start Terasology. +This command can be used in RenderDoc to attach to the running application. \ No newline at end of file diff --git a/docs/Rendering.md b/docs/Rendering.md new file mode 100644 index 00000000000..e17f2fe6ace --- /dev/null +++ b/docs/Rendering.md @@ -0,0 +1,30 @@ +**DISCLAIMER**: the Renderer is undergoing major refactoring. The information provided here is so far correct and describes the only way at this stage to access rendering functionality. A major goal of the refactoring work however is to eventually provide a much more powerful API that will allow to expand, improve and even replace the renderer functionality available. Stay tuned! =) + +## RenderSystem interface +To get the engine to call your custom rendering functions, you need to have a System implementing the [RenderSystem](http://jenkins.terasology.org/job/Terasology/javadoc/index.html?org/terasology/entitySystem/systems/RenderSystem.html) interface. This interface contains a method for some of the rendering passes executed by the engine. Add your code to the method that best fits the type of rendering you want to do. +Usually this will be either renderOpaque or renderAlphaBlend, depending on whether or not you want to display transparent objects. The functions will be called automatically, while the system is registered to the engine. + +## WorldRenderer +More often then not, you will need more information then just the description of the objects you want to render. It is likely that you also need to have access to the camera position. The [WorldRenderer](http://jenkins.terasology.org/job/Terasology/javadoc/index.html?org/terasology/rendering/world/WorldRenderer.html) can provide this amongst other useful stuff, such as block lighting information. To get access to the WorldRenderer, add a public WorldRenderer attribute to your system, with a @In annotation. The engine will assign an instance of WorldRenderer to this automatically. + + @RegisterSystem(RegisterMode.CLIENT) + class MySystem implements WorldRenderer { + @In + public WorldRenderer worldRenderer; + + ... other code ... + + public void renderOpaque() { + Camera camera = worldRenderer.getActiveCamera(); + ... rendering code ... + } + } + +## OpenGL and GLSL +Terasology uses [OpenGL 2.1](https://www.opengl.org/sdk/docs/man2/) for all it's rendering. Shaders are written in the corresponding [GLSL version 1.2](https://www.opengl.org/registry/doc/GLSLangSpec.Full.1.20.8.pdf). + +## Related Links +* [Renderer](Renderer.md) +* [OpenGL 2.1 specification](https://www.opengl.org/sdk/docs/man2/) +* [GLSL 1.2 specification](https://www.opengl.org/registry/doc/GLSLangSpec.Full.1.20.8.pdf) +* [LWJGL OpenGL package documentation](http://javadoc.lwjgl.org/index.html?org/lwjgl/opengl/package-summary.html) \ No newline at end of file diff --git a/docs/Replay-Tests.md b/docs/Replay-Tests.md new file mode 100644 index 00000000000..fa8d566f71c --- /dev/null +++ b/docs/Replay-Tests.md @@ -0,0 +1,129 @@ +# Replay Tests + +## Overview + +With the addition of the Record & Replay feature, a new module that uses replays for testing purposes was created: [TestReplayModule](https://github.com/Terasology/TestReplayModule). With this module, it is now possible to record a play session and then replay them in a testing environment to test the game. This type of test is called "Replay Test" and they + are JUnit tests that check the game right after a replay is loaded, during a replay and also when the replay ends. + +This wiki page has the purpose to explain how Replay Tests work and also how to write one of these tests. There is also an [examples package](https://github.com/Terasology/TestReplayModule/blob/master/src/test/java/org/terasology/replayTests/examples) with some examples in the module's main repository. + + +## Writing Replay Tests + +First, it is necessary to download the TestReplayModule since it has the classes necessary to create a ReplayTest. Instructions on how to fetch a module [here](https://github.com/MovingBlocks/Terasology/wiki/Developing-Modules). It is also important to put the recording that will be tested in the "assets/recordings" module's folder. The replay tests should be created in the [replayTest package](https://github.com/Terasology/TestReplayModule/blob/master/src/test/java/org/terasology/replayTests) + +There are two ways of writing replay tests: making the test class extend [AcceptanceTestEnvironment](https://github.com/Terasology/TestReplayModule/blob/master/src/main/java/org/terasology/AcceptanceTestEnvironment.java) or by having a class have a [ReplayTestingEnvironment](https://github.com/Terasology/TestReplayModule/blob/master/src/main/java/org/terasology/ReplayTestingEnvironment.java). + +### Using AcceptanceTestEnvironment + +After creating a class that extends `AcceptanceTestEnvironment`, it is necessary to implement three abstract methods. Each method is supposed to have checks that will happen in a distinct moment of a replay: +- Right after a replay is loaded, which means the RecordAndReplayCurrentStatus changes from PREPEARING_REPLAY to REPLAYING; +- During the replay, right after the initial checks are done and the status is still REPLAYING. +- On its ending, when the status changes from REPLAYING to REPLAY_FINISHED. + +Note that it is not necessary to fill every one of the three methods since it may not be desired to test the replay on each of these phases. + +**Example:** + + + @Override + protected void testOnReplayStart() throws Exception { + LocalPlayer localPlayer = CoreRegistry.get(LocalPlayer.class); + TestUtils.waitUntil(() -> localPlayer.isValid()); + character = localPlayer.getCharacterEntity(); + initialPosition = new Vector3f(19.79358f, 13.511584f, 2.3982882f); + LocationComponent location = character.getComponent(LocationComponent.class); + assertEquals(initialPosition, location.getLocalPosition()); // check initial position. + + } + + @Override + protected void testDuringReplay() throws Exception { + EventSystemReplayImpl eventSystem = (EventSystemReplayImpl) CoreRegistry.get(EventSystem.class); + TestUtils.waitUntil(() -> eventSystem.getLastRecordedEventIndex() >= 1810); // tests in the middle of a replay needs "checkpoints" like this. + LocationComponent location = character.getComponent(LocationComponent.class); + assertNotEquals(initialPosition, location.getLocalPosition()); // checks that the player is not on the initial position after they moved. + } + + @Override + protected void testOnReplayEnd() throws Exception { + LocationComponent location = character.getComponent(LocationComponent.class); + Vector3f finalPosition = new Vector3f(25.189344f, 13.406443f, 8.6651945f); + assertEquals(finalPosition, location.getLocalPosition()); // checks final position + } + +Notice that to make efficient tests in `testDuringReplay` it is necessary to add "checkpoints" with `waitUntil` so that something can be tested after a certain event is reproduced. + +With the three methods implemented, the only thing left is to create a test method that will call `AcceptanceTestEnvironment`'s `runTest` method. This method receives two parameters: The title of the recording and a boolean that indicates if the engine created for the test should be headless. + + + @Test + public void run() { + runTest("Example", true); + } + +Since `AcceptanceTestEnvironment` has a `ReplayTestingEnvironment`'s subclass, it is possible to use `ReplayTestingEnvironment`'s public methods in the test. + +### Using ReplayTestingEnvironment + +This approach is more complex than the previous one but offers more control. First create a class and make it have an instance of `ReplayTestingEnvironment`. This environment class is responsible for starting the game in a replay state while using an instance of TerasologyEngine that can be accessed by the test class. + +The next step should be to create a thread that runs `ReplayTestingEnvironment`'s `openReplay` method with the name of the recording to be played, so when the thread run, it will open a replay while the testing can be done in the main thread. + + + private ReplayTestingEnvironment environment = new ReplayTestingEnvironment(); + + /** To test the replay while it is executing, it is necessary to create a thread that will run the replay. */ + private Thread replayThread = new Thread() { + + @Override + public void run() { + try { + //This is the title of the replay to be played. It is generally the name of the folder in the 'recordings' directory. + String replayTitle = "REPLAY_TITLE"; + + /* + This opens the game and executes the replay desired for testing. The first parameter of the "openReplay" + method is the replay title, + and the second one is if the replay should be headless. + */ + environment.openReplay(replayTitle, true); + } catch (Exception e) { + throw new RuntimeException(e); + } + } + }; + + +Write a public method with `@Test` annotation as you would with a normal JUnit test. In this test, make the thread call its `start` method. As it can be seen in the code below, there are two important `waitUntil` statements that divide the code and therefore should be in every replay test. The first `waitUntil` waits for the replay to be fully loaded. The asserts that check the initial values of a replay should be written right after this `waitUntil`. The second `waitUntil` runs until the replay ends. Therefore, the asserts that check values after a replay is finished should be placed right after it. It is also possible to check something in the middle of a replay. To do that, it is necessary to write tests with "check points" between the two `waitUntil`. These "checkpoints" are `waitUntil` that waits for a certain event to be sent during a replay. For an example of one of these tests, check [ExampleReplayTest](https://github.com/Terasology/TestReplayModule/blob/master/src/test/java/org/terasology/replayTests/examples/ExampleReplayTest). + + + @Test + public void testTemplate() { + replayThread.start(); + + TestUtils.waitUntil(() -> (environment.isInitialised() && environment.getRecordAndReplayStatus() == RecordAndReplayStatus.REPLAYING)); + + TestUtils.waitUntil(() -> environment.getRecordAndReplayStatus() == RecordAndReplayStatus.REPLAY_FINISHED); + + } + + +When the tests finish their execution, it is important to close the replay properly. To do so, it is necessary to create a new public method with the `@After` annotation that calls the environment's `shutdown` method, resets the `GameThread` then waits for the thread to end by calling its `join` method. + + + @After + public void closeReplay() throws Exception { + //these last three lines are important to correctly shutdown the game after the tests are done. + environment.getHost().shutdown(); + GameThread.reset(); + replayThread.join(); + } + + +## Suggestions and Important notes + +* It is recommended to use the `AcceptanceTestEnvironment` approach since it is easier to write replay tests using it. +* Replay tests with headed engines should have a "@Ignore" annotation since Jenkins cannot run headed tests. +* Besides the `openReplay` method in the `ReplayTestingEnvironment` class, there is also an `openMainMenu` method, which opens the game in the main menu instead of opening the replay. To test replays using this method, the user has to manually select a replay to run. +* There is an [InvertedExampleReplayTest](https://github.com/Terasology/TestReplayModule/blob/master/src/test/java/org/terasology/replayTests/examples/InvertedExampleReplayTest.java) class that makes the engine run on the main thread while the tests run on another thread. This class tests exactly the same thing as the ExampleReplayTest and was created to test some things out and to show that it is possible to structure the tests in a way different from the template. diff --git a/docs/Serialization-Overview.md b/docs/Serialization-Overview.md new file mode 100644 index 00000000000..0c972d9f20d --- /dev/null +++ b/docs/Serialization-Overview.md @@ -0,0 +1,53 @@ +## Introduction +Terasology relies on [a custom system](https://github.com/MovingBlocks/Terasology/tree/develop/engine/src/main/java/org/terasology/persistence/typeHandling) to serialize Java objects of arbitrary types. It was initially written to serve as a medium to serialize objects of custom module types in components, but it has now been expanded to be a fully independent serialization library capable of serializing almost every type out-of-the-box. + +## Design +Serialization functionality is based around 3 main types: `TypeHandler`, `TypeHandlerFactory` and `TypeHandlerLibrary`. More information can be found in the classes' JavaDoc. + +### `TypeHandler` +A `TypeHandler` is responsible for serializing objects of a certain type. During the serialization process, it must convert an object to a `PersistedData` (the serialized form represented in memory) such that a similar object with the same data can be accurately reconstructed from that `PersistedData`.`TypeHandler` code should be designed to be as robust as possible; rather than throwing an exception or returning null when a field is not serializable, a `TypeHandler` should simply skip over the unserializable/unknown field and serialize the rest normally. + +It is also important to note that `TypeHandler` methods should be considered "hot" code, and any information that can be cached (like field metadata for a type) should be cached. Since the `TypeHandler`s themselves are cached, this prevents unnecessary and potentially expensive information retrieval during the serialize and deserialize methods, which may be called multiple times during the serialization of a single object. This caching process is aided by `TypeHandlerFactory`, which can provide the common cached data to the `TypeHandler` during construction. + +### `TypeHandlerFactory` +A `TypeHandlerFactory` is used to create a `TypeHandler` for the given type. The `TypeHandlerFactory` can obtain any information that the `TypeHandler` might need (like class or field metadata) and pass it along to the `TypeHandler` during construction. + +Example of a `TypeHandler` that does not require a `TypeHandlerFactory` + +### `TypeHandlerLibrary` +A `TypeHandlerLibrary` is responsible for creating `TypeHandler`s for various types. To obtain the `TypeHandler` for a specific type, it iterates through all registered `TypeHandlerFactory`s and asks each of them to create a `TypeHandler` for the given type; the first successfully generated `TypeHandler` is returned. The iteration is done so that factories that are registered later are given precedence over factories registered first. This allows consumers to override default type handling behaviour for specific types depending on their needs. + +The `TypeHandlerLibrary` caches type handlers for various types. Since a single type's `TypeHandler` may be retrieved multiple times while serializing a single object, this cache helps avoid calling the expensive `TypeHandler` creation process (via `TypeHandlerFactory`) multiple times for efficiency. While the `TypeHandlerLibrary` only deals with type handlers, it is also possible to "register" a `TypeHandler` for a given type using `addTypeHandler` -- under the hood, this method just creates a `TypeHandlerFactory`. + +The `@RegisterTypeHandler` and the `@RegisterTypeHandlerFactory` annotations can also be used to register type handlers and type handler factories to the `TypeHandlerLibrary` in the `Context`. + +### Examples + +#### `TypeHandler` without a `TypeHandlerFactory` +- [`IntTypeHandler`](https://github.com/MovingBlocks/Terasology/blob/develop/engine/src/main/java/org/terasology/persistence/typeHandling/coreTypes/IntTypeHandler.java) + +These are registered using the `TypeHandlerLibrary.addTypeHandler` method. + +#### `TypeHandler` and `TypeHandlerFactory` pair +- [`CollectionTypeHandler`](https://github.com/MovingBlocks/Terasology/blob/develop/engine/src/main/java/org/terasology/persistence/typeHandling/coreTypes/CollectionTypeHandler.java) and [`CollectionTypeHandlerFactory`](https://github.com/MovingBlocks/Terasology/blob/develop/engine/src/main/java/org/terasology/persistence/typeHandling/coreTypes/factories/CollectionTypeHandlerFactory.java) + +Only the `TypeHandlerFactory` has to be registered via the `TypeHandlerLibrary.addTypeHandlerFactory` method; the `TypeHandler` does not need to be registered separately. + +## Workflow +The workflow for (de)serializing an object is as follows: +- Retrieve the `TypeHandler` for its type from the `TypeHandlerLibrary` (using `getTypeHandler`) +- (De)serialize the object using the retrieved `TypeHandler`. + +Depending on the serialization format used, the `TypeHandler` must be provided with appropriate `PersistedData` and `PersistedDataSerializer` instances. To make the process easier, Terasology provides the `AbstractSerializer` utility class, implementations of which provide helper methods to easily serialize and deserialize objects to disk using the preferred format. + +### Supported Formats +Terasology currently supports JSON (via Gson) and binary (via Protobuf) serialization. + +- To serialize objects in JSON, use the `GsonPersistedData` and `GsonPersistedDataSerializer` classes or the `GsonSerializer` utility class. +- To serialize objects in binary, use the `ProtobufPersistedData` and `ProtobufPersistedDataSerializer` classes or the `ProtobufSerializer` utility class. + +## Features +- Format independent -- code that serializes an object remains the same regardless of the target format. +- Supports almost every possible type out-of-the-box. +- Supports recursive types (i.e. types that refer to themselves) but not cyclic object references. +- It is possible to override default serialization behavior by specifying a new `TypeHandler` that handles a type differently. \ No newline at end of file diff --git a/docs/Setting-up-a-Light-Environment.md b/docs/Setting-up-a-Light-Environment.md new file mode 100644 index 00000000000..53e3842dc26 --- /dev/null +++ b/docs/Setting-up-a-Light-Environment.md @@ -0,0 +1,89 @@ +# Introduction +Every day, bit by bit, Terasology is growing. From the smallest of jobs like adding readmes to slightly larger jobs like adding code, people from all around the world wish to contribute to the project. However, for many the process is far more complex than required. For instance, one doesn't need to clone a complete Git-linked repository to one's system just to edit a readme. This guide will guide you through setting up a light environment so that you can do these relatively small tasks without much tedium. + +# Using the GitHub Web Interface +GitHub's web interface is great for tasks involving small edits to code or edits to text files (like readmes) or wikis. It allows the user to edit and commit right from the browser window. + +## When *not* to use the web interface + +Before detailing how to use the web approach it is worth highlighting when **not** to use it, as we often see the web interface used for work that really needs a [full engine workspace](https://github.com/MovingBlocks/Terasology/wiki/Preparing-an-Engine-Workspace) - anything that results in a testable change in the game (or other _compiled_ bits of code and resources) should really be done in an [IDE](https://en.wikipedia.org/wiki/Integrated_development_environment) to take advantage of the tooling to build and [analyze](https://github.com/MovingBlocks/Terasology/wiki/Checkstyle) your changes. This makes sure your changes follow the [project code style](https://github.com/MovingBlocks/Terasology/wiki/Common-Style-Points) and other guidelines, and lets you run the game to test that your work actually achieves your objective. That way you can also verify that you have good testing instructions to place in a Pull Request (PR), take screenshots if appropriate, and so on. + +Making a change using the web UI bypasses most such checks - syntax, style, code smells, testing, and so on. So it remains best to limit use of the web UI to editing documentation and making simple fixes like typos. You are of course free to do what you wish in a fork, especially if perhaps you are sharing it with a few friends, but don't be surprised if the quality standards for having a PR merged runs into the web-based workflow as a negative for changes outside the simple ones this workflow does well :-) + +In some cases there may be a hybrid approach: using a full Web IDE such as https://www.gitpod.io so you can test your changes without a local workspace. This works for instance for [Destination Sol](https://github.com/MovingBlocks/DestinationSol) as it is less demanding for 3D graphics, but not so well for Terasology (the game runs, but lags intensely) + +## Creating a Fork +To create a fork of Terasology, visit [Terasology's GitHub repository](https://github.com/MovingBlocks/Terasology) and click the "Fork" button near the top right corner of the screen. This will create a fork of the repository in your GitHub account. + + +## Creating and Deleting Branches +Since you are going to be making changes, it might be a good idea to create a branch before. You can create a branch by clicking on the repository's branch selector and typing in the name of the branch. If the branch doesn't exist, GitHub will offer to create it for you. + +You can go to the *Branches* page of your repository by clicking on the number of branches displayed on the home page of the repository. This will take you to an overview of all your branches. From here, you can delete branches by clicking the little red trash can icons. + + + +## Editing +### Creating a File +1. Navigate to the main page of your repository. +2. Browse to the folder where you want to create a file. +3. Click the *Create new file* button above the file list. +4. Type the name and extension of the file you want to create in the name field. You may also create subdirectories here by using the `/` directory separator. +5. Add contents to the file in the *Edit new file* tab. You may preview your file while editing using the *Preview* tab. +6. At the bottom of the page, type a commit message, choose the branch you want to commit to, and then click the *Commit New File* button. + + +### Editing, Renaming or Moving Files +1. Browse to the file you want to make changes to. +2. In the upper right hand corner, click the little pencil icon to open the editor. +3. You can change the name of the file at the top of the page. You can also move the file by using the `/` separator to make/access subdirectories (use `..` to go to the parent directory). +4. Make the changes you want to make in the *Edit* tab. You may preview the changes using the *Preview* tab. +5. Scroll to the bottom of the page, type a commit message, choose the branch you want to commit to, and click the *Commit Changes* button. + + + +### Deleting files +1. Browse to the file you want to delete. +2. At the top of the file, click the little trashcan icon. +3. Scroll to the bottom of the page, type a commit message, choose a branch, and commit. + + +## Opening a Pull Request +1. Navigate to the home page of your repository. +2. Press the *Pull Request* button at the top of the page. +3. Give a title and description to the pull request. +4. Press the *Create a pull request* button. + + +# Using the GitHub Desktop Client +For many changes, especially more elaborate ones, you may prefer downloading the repository on your system, making changes, testing them and then committing them. This can be achieved by various means, the most popular of which is git's command-line interface. However, this may be daunting for many users, especially beginners. This is where GitHub's desktop client comes in. The GitHub desktop client is an easy way to clone and edit repositories on your system. Here are a few tips to help you get started. + +Note that to access your environment via the desktop client, you first need to fork the [Terasology repository](https://github.com/MovingBlocks/Terasology) using the process mentioned before in this document. + +## Setting Up the Client +The GitHub desktop client can be downloaded from [the GitHub desktop home page](https://desktop.github.com). The client is available for MacOS and for Windows. Sadly, there is no Linux client yet. +On launching the client for the first time, you will be asked to enter your GitHub account username and password, after which you will be led through a short tutorial on the basics of using the client. + +## Cloning Your Repository +1. Launch the client. +2. Press the `+` dropdown in the top left corner. +3. Go to the *Clone* tab. +4. Select the name of the forked repository from the list of all your repositories. + + +## Creating a Branch +1. Click on the create branch icon. +2. Type in a name and select the original branch from which to branch off. +3. Press the *Create Branch* button. + + +## Making Changes and Committing +Sadly, the desktop client doesn't support making changes or browsing the repo. You will need to browse the repo and make changes using the operating system's file explorer and appropriate editing tools on your system. To commit, simply select the repository in the tray on the left hand side, select which files to commit, type a commit message and description and press the *Commit* button. You can push committed changes by pressing Control+P (Cmd+P on Mac) or by using the *Publish* button at the top right corner of the screen. You can also use the toolbar item at Repository -> Push. + + +## Opening Pull Requests +1. Select your repository in the tray at the left. +2. Press the *Pull Request* button in the top right corner. +3. Provide a title and description. +4. Press *Send Pull Request*. + diff --git a/docs/Setup-a-headless-server.md b/docs/Setup-a-headless-server.md new file mode 100644 index 00000000000..665d95673c9 --- /dev/null +++ b/docs/Setup-a-headless-server.md @@ -0,0 +1,15 @@ +# Setup a headless server + +This can be achieved with different approaches. + +1. For all operating systems with installed java 11 + - Download the Omega Release + - execute: `java -jar Terasology.jar --headless` + - Then you get a Terasology server running at port 25777 + - For configuration of the server look at the typical place for the config +2. For Linux servers with installed **docker** daemon + - Take a look at: https://hub.docker.com/r/qwick/terasology/ + - And please report any issues, **relating to the docker image**, at https://github.com/qwc/docker-terasology +3. Start a headless server from source + - `gradlew server` + - or via Intellij run configuration `TerasologyPC (Headless)` diff --git a/docs/Shape-File-Specifications.md b/docs/Shape-File-Specifications.md new file mode 100644 index 00000000000..3d1d5186f85 --- /dev/null +++ b/docs/Shape-File-Specifications.md @@ -0,0 +1,92 @@ +*Note: This page is still under construction!* + +In Terasology, [block shapes](Block-Shapes.md) are defined in **.shape** files. These are JSON files (technically, [GSON](https://github.com/google/gson) which provide rendering mesh data, physics collision data, and mouse collision data for Terasology's voxel blocks. + +This page lists the Shape File format's specification standards, and their history. + +# 1.1 - Unreleased, 2020 + +The Shape File format is currently undergoing development to increase both versatility and efficiency. It retains partial backwards compatibility; 1.0 files remain fully valid in the 1.1 standard, but a parser that expects a 1.0 file will likely be unable to parse a 1.1 file. + +Significant improvements over 1.0 include the ability to define multiple directions in which a section should be rendered, as opposed to either a single direction or always being rendered; the ability to define more than one section to be rendered in any given direction; and no longer requiring data to be duplicated when different points within a section share vertex, normal, or UV data with each other. + +## Changes + +### First-level parameters + +- Sections are no longer restrained to being named "front", "back", "top", "bottom", "left", "right", and "center" as in 1.0. They may be given any unique identifier which does not conflict with other parameters of the shape file, regardless of capitalization ("author", "collision", "displayName", and "exportDate" cannot be used as section names). + +### Section Object parameters + +- "faces" of a section may represent a point with an array of 3 integer indices, corresponding to "vertices", "normals", and "texcoords" of the section, as opposed to a single integer index that is used for all three. Index arrays and single indices may be used interchangeably within the same face. + +- "vertices", "normals", and "texcoords" within a section are no longer required to be the same length, as faces can refer to each list individually. + +- Sections have an optional "sides" parameter that defines valid directions for the section to be rendered. It may be presented as a decimal integer, a single Unicode character, a binary integer, or a valid directional name. If not included, it will use the name of the section as a fallback, as in 1.0 files. + +## Full Standard + +Coming soon. + +# 1.0 - Feb. 17, 2014 + +After the addition of the "displayName" parameter, the Shape File format as parsed by Terasology would remain unchanged for 6 years. Thus it has been retroactively declared as Shape File 1.0, the standard specification in use prior to 2020. + +## Full Standard + +### First-level parameters + +All first-level parameters are to be treated as optional. The absence of any first-level parameter should not result in an error. + +| Parameter | Type | Description | +| ---------------- |:----------------:| :--------------------------------------------------------------------| +| **"author"** | String | This string represents the name of the person who created this block shape. | +| **"collision"** | Collision Object | The collision parameter represents information about the rotational and collision data of the shape. | +| **"displayName"**| String | This string is added to the end of a block's display name when the block is using this shape. | +| **"exportDate"** | String | This is a [RFC 3339](https://tools.ietf.org/html/rfc3339) timestamp in the form of "YYYY-MM-DD hh:mm:ss", intended to display when the shape was last modified within an editing program (such as Blender). | +| **"front"** | Section Object | Section data representing the front (Z-) side of the block. | +| **"back"** | Section Object | Section data representing the back (Z+) side of the block. | +| **"left"** | Section Object | Section data representing the left (X-) side of the block. | +| **"right"** | Section Object | Section data representing the right (X+) side of the block. | +| **"top"** | Section Object | Section data representing the top (Y+) side of the block. | +| **"bottom"** | Section Object | Section data representing the bottom (Y-) side of the block. | +| **"center"** | Section Object | Section data representing part of the block that should be rendered regardless of visible directions.| + +### Collision Object parameters + +As with first-level parameters, all collision object parameters should be treated as optional. + +| Parameter | Type | Description | +| ---------------- |:----------------:| :--------------------------------------------------------------------| +| **"colliders"** |Array (Collider Object)| A list of collider objects that represent the collision data for the shape. An empty list is valid, and will result in a simple full cube being used. +| **"convexHull"** | Boolean | If present (regardless of true OR false) the "colliders" parameter will be ignored, and a convex hull will be calculated for the shape. If neither "colliders" nor "convexHull" is present, a simple full cube will be used. | +| **"symmetric"** | Boolean | If true, sets symmetry along all three axes and overrides pitch, roll, and yaw, if present. | +| **"pitchSymmetric"** | Boolean | If true, sets symmetry around the X axis. | +| **"rollSymmetric"** | Boolean | If true, sets symmetry around the Z axis. | +| **"yawSymmetric"** | Boolean | If true, sets symmetry around the Y axis. | + +### Collider Object parameters + +If the "type" parameter is omitted, the collider should be ignored entirely. If "type" is "AABB", omitting the "position" or "extents" parameters should result in an error. If the "type" is "Sphere", omitting the "radius" parameter should result in an error. + +| Parameter | Type | Description | +| ---------------- |:----------------:| :--------------------------------------------------------------------| +| **"type"** | String | Either "AABB" (axis-aligned bounding box) or "Sphere". | +| **"position"** | Vector3F | The center (*not* origin) of the collider. | +| **"extents"** | Vector3F | The full width (*not* distance from center) of the collider. Only valid for type "AABB". | +| **"radius"** | Float | Only valid for type "Sphere". | + +### Section Object parameters + +"vertices", "normals", and "texcoords" arrays must be identical in length, and if any of the three arrays is a different size, it will result in an error. + +| Parameter | Type | Description | +| ---------------- |:----------------:| :--------------------------------------------------------------------| +| **"vertices"** | Array (Vector3F) | The list of vertex coordinates. | +| **"normals"** | Array (Vector3F) | Normal data (-1 to 1) for each vertex. | +| **"texcoords"** | Array (Vector2F) | The UV map coordinates (0 to 1) for each vertex, | +| **"faces"** | Array (Array(Int)) | The list of face information. | + +### Face parameters + +The "faces" array of a section contains any number of face definitions. Faces consist of arrays of integers, where each integer is the index of an included vertex in the "vertices" list. All vertices in the face should be listed in clockwise order. If an integer is outside the bounds of the vertices list (either a negative number, or greater than the length of the vertices array), it should result in an error. \ No newline at end of file diff --git a/docs/Supported-Development-Workflows.md b/docs/Supported-Development-Workflows.md new file mode 100644 index 00000000000..366ed14a1e3 --- /dev/null +++ b/docs/Supported-Development-Workflows.md @@ -0,0 +1,96 @@ +# About + +This document is aimed at those who are testing the development environment itself, i.e. to make sure that a change to the build configuration hasn't broken another contributor's workflow. + +## Help Wanted: 🧩 + +A 🧩 symbol in this document indicates an incomplete section. This is a wiki, please help here you can! + +If you have questions about what's needed or you want to someone to look over what you've written before you commit it, ask us in the `#logistics` channel of [Discord](Home.md#joining-the-community--asking-for-help). + +# Engine, Subsystems, Facade + +## Gradle `game` + +`gradlew game` builds the PC facade, the engine, and its subsystems. + +It rebuilds any classes that have had source changes in any of these. +It does not spend time rebuilding things that have not changed. + +It starts a new process running the PC facade. +All dependencies are provided on the classpath. + +## Run _TerasologyPC_ + +In IntelliJ IDEA, running the `TerasologyPC` configuration serves the same purpose as `gradlew game` does. + +Some implementation details may differ, such as: + +* the exact construction of the classpath + +If IntelliJ is building after a previous gradle build, IntelliJ **MAY** decide to build some things itself rather than relying on gradle's previous build result, but it **SHOULD NOT** spend time re-building things it already built if they have not changed. (Unless you explicitly _Rebuild Project_.) + +## Distribution + +🧩 notes about this in [#4347](https://github.com/MovingBlocks/Terasology/pull/4347). + + +## Debugging + +### Breakpoints + +🧩 + +### Method Reloading + +🧩 + +## reflections.cache + +🧩 Is currently [not built for local classes at all](https://github.com/MovingBlocks/Terasology/pull/4157#issuecomment-708589181), only for jars? That MAY be changed, but we might end up with an alternate implementation that uses something else before that happens. + + +# Modules + +## Gradle `game` + +In addition to the subprojects mentioned in the **Engine** section above, `gradlew game` _also_ builds all module subprojects present in the `/modules` directory. + +If a subproject under `/modules` depends on a module that is _not_ part of the current build, +a jar file for that dependency will be put in `/cachedModules`. + +The `/modules` projects and `/cachedModules` **MUST NOT** be on the classpath of the game process. (Modules being on the classpath broke the sandbox, see [#4375](https://github.com/MovingBlocks/Terasology/issues/4375).) + +All locally-built modules and the modules they depend on must appear in the Advanced Game Setup screen. + +(🧩 and also in the logs somewhere?) + +If a module is present as a local subproject, that **MUST** be the version of the module used by the game. (i.e. it must not load those classes from a jar it got from another repository.) + +## Run _TerasologyPC_ + +(same) + + +## Asset Reloading + +🧩 TO DOCUMENT: there's some asset-reloading stuff that's supposed to happen _without_ using any IntelliJ debugger features and _without_ needing to (re)build a jar file. + +Does it apply equally to all types of assets? e.g. prefabs, meshes, textures, translations. Probably not: [DW notes only a few asset types are possible](https://github.com/MovingBlocks/Terasology/pull/4157#issuecomment-708589181). + +See [note about asset location during editing](https://github.com/MovingBlocks/Terasology/pull/4157#issuecomment-735016251). + +## Versions + +The version number of a module is defined by the `version` field in its `module.txt`. Its version number **MUST** appear identically in `gradlew 🧩` and in-game in the Advanced Game Setup screen. + +## Module Downloader + +🧩 something at runtime sometimes puts `.jar` files in `$homeDir/modules/`? and if they overlap with something provided by gradle dependencies, then it should explode, or use one, or the other? + + +# Other Dependencies + +Running Terasology while developing one of its dependencies outside of the `MovingBlocks/Terasology` project, such as TeraNUI. + +See [Using Locally Developed Libraries](Using-Locally-Developed-Libraries.md). diff --git a/docs/Teracon-2017-Slides-about-multiplayer.md b/docs/Teracon-2017-Slides-about-multiplayer.md new file mode 100644 index 00000000000..ee20e384d47 --- /dev/null +++ b/docs/Teracon-2017-Slides-about-multiplayer.md @@ -0,0 +1,78 @@ +Simplified in a multiplayer game you have: +* A server +* Multiple clients + +However it is better to see it role wise: +* Authority +* Client: + * Visual + Audio output + * Masking of delay till server confirmed action + +Example: +* Client: Handles left click by sending "attack request" to authority +* Authority: Authority determines outcome of "attack request" and informs clients + +While we have only 2 roles, terasology has 4 modes it can run in: +* Headless / dedicated server: + * Roles: Authority +* Remote client + * Roles: Client +* Single player: + * Roles: Authority and Client +* Listen server: + * Roles: Authority and Client + + +How to let code only run in certain modes: +* Either for complete system class: `@RegisterSystem(RegisterMode.AUTHORITY)` +* Or per method: `@ReceiveEvent(netFilter = RegisterMode.CLIENT)` + + +Besides CLIENT and AUTHORITY there are 2 more modes: +* ALWAYS + * The default +* REMOTE_CLIENT + * For exotic optimizations + +Typical bugs when multiplayer does not get kept in mind: +* Code for authority relies on something that got only created for the client + * Code might fail only on "Headless server", and possibly on listen server when different client triggers action +* Code for client tries to do something that it has no permission for + * Code fails only on remote clients +* Code that does not take network delays into account + * Not responsive feeling on remote clients + * Animations are not smooth + +This means: +* Testing with headless + remote client is necessary +* Headless + Modules => Painful to setup +* Multiplayer testing is time consuming + +Long term vision: +* Singleplayer = listen server = headless server + remote client + * Testing multiple modes would no longe be needed + * Network delay could be simulated ingame for testing + +This would mean: + * Client sees no authority data + * Authority sees no client data + * Data exchange only via (simulated) network + +In ideal world: +* There would be no static variables +* No CoreRegistry ! + +This would allow for: +* Separate `Context` instances +* authority related entities in authority entity manager +* UI related entites in client entity manager +* Constant data gets shared + +Some ideas that take less effort: +* Option to start headless from UI + * Instead of normal game + * Possibly offers settings for bad network simulation +* Class loader tricks to allow for "headless server + remote client" in one JVM + +Synchronization part: + * See [Entities, Components and Events on the Network](Entities-Components-and-Events-on-the-Network.md) \ No newline at end of file diff --git a/docs/Testing-Modules.md b/docs/Testing-Modules.md new file mode 100644 index 00000000000..9c8123102eb --- /dev/null +++ b/docs/Testing-Modules.md @@ -0,0 +1,37 @@ +## Unit Tests + +The build server runs `gradlew unitTest` to run [JUnit](https://junit.org/junit5/) tests included in your module. + +## Integration Tests + +Unit tests that are each focused on the behavior of a small amount of code +are the best at giving you fast feedback and a precise description of what's wrong. + +Sometimes that's not enough, and you also need ***integration tests***: +scenarios that test the integration of your system with the engine +and the other modules it depends on. + +Terasology provides extensions to JUnit that will help set up a fully configured engine and module environment for your integration tests: [`engine-tests:org.terasology.engine.integrationenvironment`](https://github.com/MovingBlocks/Terasology/tree/develop/engine-tests/src/main/java/org/terasology/engine/integrationenvironment) + +🚧 **TODO**: set up a javadoc server that includes classes from `/engine-tests/src/main/`. + +## Logging + +Terasology can produce a _lot_ of log output, especially during integration tests. + +You can edit the file `src/test/resources/logback-test.xml` to adjust which log messages will get recorded. +This is a configuration file for Logback-Classic version 1.2. Refer to the [Logback manual](https://logback.qos.ch/manual/) for details. + +If your module does not have `logback-test.xml` at all, +run `groovyw module refresh` to get a default configuration you can use as a starting point. + +Logback configuration files in your module will only apply when running tests, +not while running the game itself. +The configuration for the game is in [`/facades/PC/src/main/resources/logback.xml`](https://github.com/MovingBlocks/Terasology/blob/develop/facades/PC/src/main/resources/logback.xml). + +## See also + +* [Developing Modules](Developing-Modules.md) - how to edit an existing module, or create a new one +* [Modding API](Modding-API.md) - the methods a module is allowed to call +* [Module Dependencies](Module-Dependencies.md) - how to deal with modules that depend on another +* [Dealing with Forks](Dealing-with-Forks.md) - work with your own copies of GitHub repos you can write to diff --git a/docs/Text-and-Font.md b/docs/Text-and-Font.md new file mode 100644 index 00000000000..3a95dce9bdc --- /dev/null +++ b/docs/Text-and-Font.md @@ -0,0 +1,61 @@ +# Fonts + +Terasology uses [Google's Noto Font](https://www.google.com/get/noto/) +for most text rendering operations. The font was chosen, because: + +* The font is [open source](https://github.com/googlei18n/noto-fonts) +(SIL Open Font License, Version 1.1) +* Supports many languages +* Supports symbols through [Noto Sans Symbols](https://www.google.com/get/noto/#sans-zsym) +* Supports emoji - currently not used though +* Supports italic and bold font styles +* Looks good + +The font is sampled at different sizes and converted into 2D +textures using [BMFont 1.14 +beta](http://www.angelcode.com/products/bmfont/). +The following Unicode groups are used: + +* Latin + Latin Supplement (0000) +* Latin Extended A and B (0100) +* IPA Extensions (0250) and Spacing Modifier Letters - In sum, +everything in [0001-0300] +* Greek, Coptic, Cyrillic+Supplement (0370-0530) +* Greek Extended (1F00) +* Subscripts, superscripts (2070) +* Currency Symbols (20A0) +* Arrows (2190) +* Mathematical Operators (2200) +* Box Drawings (2500) +* Geometric Shapes (25A0) +* Miscellaneous Symbols (2600) + +These characters are present in the regular/bold/italic/large font +textures. + +For Japanese language support, the Hiragana and Katakana font glyphs have been added from the corresponding font (CJK-jp). + +* CJK Symbols and Punctuation (3000) +* Hiragana (3040) +* Katakana (30A0) + +On top of that, the regular and regular large font textures +support the following Unicode characters from the corresponding Symbols +font: + +* Enclosed Alphanumerics (only 2460-2474 and 24B6-24EB) +* Dingbats (2700) + +The individual character codes can be used from Java code through char +constants in the classes in the ` org.terasology.unicode` package. A +similar constant collection has been made by the [Java UniCode Constants +(UCC) package by +CodeCop](http://blog.code-cop.org/2007/08/java-unicode-constants.html). + +The `fnt` files have been manually merged to get the symbols characters +into the regular font. The raw files, BMFont installation files, etc. +can be found in TeraMisc: + +https://github.com/MovingBlocks/TeraMisc/tree/master/fonts + +Combined Unicode characters (larger than FFFF) are not supported. \ No newline at end of file diff --git a/docs/Textures.md b/docs/Textures.md new file mode 100644 index 00000000000..fd13effa0a7 --- /dev/null +++ b/docs/Textures.md @@ -0,0 +1,41 @@ +This page should give you an overview of how Terasology uses textures and how you can use them on your own. + +# Location +As textures are programme Assets, they can be found in the `asset` folder of the main programme or some +modules. The different textures are then ordered by their intended usage, e.g. `blockTiles` or model textures. + +# BlockTiles (subfolder) +A very basic use of textures are the _blockTiles_, the textures for single blocks. They can be found in +`src/main/resources/assets/blockTiles` or in the `blockTiles` subfolder of module's `asset` folder. + +At the moment the size of block textures is restricted to **16x16 pixels**. They are stored as **.png** files and can + contain transparency, e.g. for colored Glass. + +Block textures need to have the same name as the corresponding JSON block definition to be auto loaded. + +# Textures (subfolder) +Any textures that are no block tiles are located in `src/main/resources/assets/textures` or the corresponding mod +directories. You can find several types of image files in there: + +* _color gradients_ for grass or foliage +* _GUI icons and backgrounds_ - elements assigned to the user interface, such as icons, inventory backgrounds, ... +* _Skybox textures_ +* _Effect textures_ such as breaking a block or the overlayed vignette +* _model textures_ such for the monkey heads + > Note: Models and its textures/materials should be sourced out to modules. + +# Override +Because of the _Override Functionality_ for mods it is possible to override core textures. For more information see + [Deltas and Overrides](https://github.com/Terasology/TutorialAssetSystem/wiki/Deltas-and-Overrides). + + Since the texture that is loaded first is used in the game, the override process is not deterministic at the moment + and one cannot guarantee which texture will take effect. + +# Known issues +* Using greyscale textures for grass or foliage works well for placed blocks (color grading), +but the icons still show up in grey color. +* `effects.png` cannot be overriden because its early loaded by the shader. Therefore, +custom texture packs need to use the default segmentation for `grassSide` to get the color grading right. + +# Related links +* [Asset System Tutorial](https://github.com/Terasology/TutorialAssetSystem/wiki) diff --git a/docs/Translation-Guide.md b/docs/Translation-Guide.md new file mode 100644 index 00000000000..66dd9ed27ea --- /dev/null +++ b/docs/Translation-Guide.md @@ -0,0 +1,21 @@ +Adding new languages to the game or helping out with translating single strings is easy and helpful as it allows players from all over the world to enjoy the game, unhindered by language barriers! + +First off, to keep things nice and clean, we advise you to work on the translation using a **feature branch**: + +- `git checkout develop` +- `git branch i18n/{{your-language}}` +- `git checkout i18n/{{your-language}}` + +To create a new language file, copy [`menu_en.lang`](https://github.com/MovingBlocks/Terasology/blob/develop/engine/src/main/resources/assets/i18n/menu_en.lang) to a new file called `menu_xx.lang` in [`engine/src/main/resources/assets/i18n`](https://github.com/MovingBlocks/Terasology/blob/develop/engine/src/main/resources/assets/i18n/) - `xx` should be an [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) two-letter code for your language. +Next up, translate everything in `menu_xx.lang` to your target language! +Every now and then, check up on your in-progress translation - the game's language can be changed in the _Settings - Player_ menu. +Some possible issues that may occur are long strings breaking UI elements and special characters not being rendered properly. + +When your translation is finished, add a tiny flag to represent the language in the settings! +To do this, download an appropriate 16x11 icon from the [famfamfam.com icon pack](http://www.famfamfam.com/lab/icons/flags/) (or create your own 16x11 icon) and place it inside [`engine/src/main/resources/assets/textures/ui/icons`](https://github.com/MovingBlocks/Terasology/tree/develop/engine/src/main/resources/assets/textures/ui/icons). +Rename it to `flag_xx.png`, `xx` being the two-letter code you've used before. + +Submit your translation as a pull request. +See [Contributor Quick Start](Contributor-Quick-Start.md) and [Dealing with Forks](Dealing-with-Forks.md) for help. + +And while you're at it, feel free to add yourself to [Credits.md](https://github.com/MovingBlocks/Terasology/blob/develop/docs/Credits.md) as a new contributor! diff --git a/docs/Troubleshooting-Developer.md b/docs/Troubleshooting-Developer.md new file mode 100644 index 00000000000..b239be7a7b0 --- /dev/null +++ b/docs/Troubleshooting-Developer.md @@ -0,0 +1,133 @@ +## Terasology + +### How to enable debug logs + +When troubleshooting Terasology, debug logs can help you identify issues or get additional information you can use to narrow down the origin of an issue to then investigate further, for instance using the IntelliJ debugger. + +You can adjust the log level(s) for Terasology in `facades/PC/src/main/resources/logback.xml`. +The default setting (currently) looks as follows: + +```xml + <logger name="org.terasology" level="${logOverrideLevel:-info}" /> +``` + +The first part, `logOverrideLevel`, refers to the log level that can be configured in the launcher's advanced settings. +When running Terasology from source, the second part will be used instead. + +To enable debug logs, set the second part to "debug": + +```xml + <logger name="org.terasology" level="${logOverrideLevel:-debug}" /> +``` + +Debug logs for all of Terasology including the engine and all modules can be a bit overwhelming. +This is why, you can add fine granular custom log-level overrides. +This works in both ways, i.e., you can increase or decrease the log level for specific packages or classes by adding lines similar to the following: + +```xml + <logger name="org.terasology.engine.world" level="debug" /> + <logger name="org.terasology.module.health.systems.HealthAuthoritySystem" level="error" /> +``` + +### Failed to create window + +Symptom: You cannot start Terasology as it will crash and show you an error popup stating "Failed to create window" + +Logs: +``` +[main] ERROR GLFW - Received error. Code: 65543, Description: GLX: Failed to create context: BadValue (integer parameter out of range for operation) +[main] ERROR o.terasology.engine.TerasologyEngine - Failed to initialise Terasology +java.lang.RuntimeException: Failed to create window + at org.terasology.engine.subsystem.lwjgl.LwjglGraphics.initWindow(LwjglGraphics.java:155) + at org.terasology.engine.subsystem.lwjgl.LwjglGraphics.postInitialise(LwjglGraphics.java:81) + at org.terasology.engine.TerasologyEngine.postInitSubsystems(TerasologyEngine.java:295) +``` + +This can happen if you switched monitors, reconfigured your monitor's resolution or updated your OS. +To resolve this, you can try to restart your system, delete `config.cfg` from your Terasology workspace root directory and re-attempt to start it. + +## IntelliJ + +* Do use IntelliJ's "Import Gradle Project" offering. Terasology supports this with IntelliJ IDEA versions 2020.1 and later. +* For a first time install of IntelliJ you may not have a defined JDK available at a platform level. Look at `File -> Project Structure -> SDKs` and use the green + if needed to point to a local JDK 11. If not you may get errors about basic Java language features missing. + * After setting this up or if you name your JDK something other than the default "11" you may have to set that to the Project SDK, again on the Project Structure page. +* Any time you change the overall project structure by adding/deleting modules or pull updates from elsewhere that contain library changes, IntelliJ will have to re-sync with gradle to learn about the new configuration. If it doesn't do so automatically, use the 🔄 _Load Gradle Changes_ action in the Gradle tool window. + +### Stale Build State + +Sometimes IntelliJ will end up in a stale build state. One of the symptoms you'll see if that is the case are problems with `/splash/splash_1.png` on trying to start / debug Terasology. + +In order to resolve this stale build state, go to the IntelliJ menu bar, click on "Build" and then on "Rebuild project". +Wait until the project was rebuilt and then try to start / debug Terasology again. + +### Resetting a buggy IntelliJ Config + +Sometimes your workspace seems to be messed up, e.g. you're facing missing run configurations, buggy code navigation, or similar issues. +In these cases, you can try to reset your IntelliJ config in order to get a clean state. You can do so by following these steps: +1. Close your project inside IntelliJ and then close IntelliJ itself +1. Run `gradlew cleanIdea` to wipe any existing IntelliJ config in your workspace +1. Open IntelliJ (should be at its non-project screen with short-cuts to create or open a project) +1. Click on "Open project" and select the build.gradle at the root of your Terasology workspace (make sure you open it as a project / allow it to import via Gradle) +1. When it opens it will take some time to index all the files and import everything properly + +### Compile Errors relating to Protobuf + +IntelliJ sometimes circumvents tasks that generate resources required for compilations, e.g. protobuf sources. +If you're seeing compilation errors relating to protobuf then you might need to run `gradlew genProto` to generate these sources. + + +## Java + +* It can be tricky to make sure the right version of Java is being used in different situations (within an IDE, via command line, on a server ..) - check the following options if needed: + * System `JAVA_HOME` environment variable + * System `PATH` environment variable + * The `update-alternatives` or `update-java-alternatives` commands available on some Linux systems can override what's set via `JAVA_HOME`. See [this Ask Ubuntu thread](http://askubuntu.com/questions/159575/how-do-i-make-java-default-to-a-manually-installed-jre-jdk) or check Google. +* The Java installation picker (which download you get from https://www.java.com/en/download) may give you a 32-bit installer if you're using a 32-bit browser on a 64-bit system. Use 64-bit if you can! + * Use `java -version` to find out what you have. This in turn may also depend on your OS. For instance, Windows may default a command prompt to `C:\Windows\System32` which will give you bad info. Try from `C:\` or anywhere else instead. + * The 64-bit version explicitly states it is 64-bit (like `64-Bit Server VM`) where 32-bit may call itself something like `Client VM` +* If you do development and have something like Android Studio installed you may have had your system classpath modified. This can cause trouble if a system version of some Java dependency gets used in favor of a version we bundle. + * Example: If you get an error like `Caused by: java.lang.UnsatisfiedLinkError: Can't obtain static method fromNative(Method, Object) from class com.sun.jna.Native` then try running the game with `java -Djna.nosys=true -jar libs/Terasology.jar --homedir=.` to ignore the system-provided version of JNA +* You can get the JVM in different implementations, e.g., _HotSpot_ or _OpenJ9_. Even though these Java virtual machine implementations are fully compliant with the JVM Specification this may lead to issues when running Terasology. **There is a known issue with OpenJ9 when starting a game** (April 2021). We recommend to us a JDK with a HotSpot JVM. + + ``` + 21:00:03.779 [main] ERROR o.t.module.sandbox.ModuleClassLoader - Denied access to class (not allowed with this module's permissions): java.io.Serializable + ``` + +## Linux + +* Watch out for line-ending issues. For instance, the `gradlew` script might throw an error like `bash: ./gradlew: /bin/bash^M: bad interpreter: No such file or directory` if it somehow ends up with Windows-style line endings. +* If having issues with SSL when using `gradlew`, run `update-ca-certificates -f` as root (or using `sudo`). +* If xrandr is being used to set a custom resolution, the game could possibly crash on launch due to lwjgl's xrandr configuration parsing. To fix, make sure the configuration mode name follows the format `"3000x2000"` instead of `"3000x2000_60.00"` or `"3000by2000"`. +* Sometimes while using the debugger, the mouse could get 'grabbed' by LWJGL making it hard to go through variable values. This handy little trick allows you to create another mouse pointer. The game only grabs one leaving you with the other to use. https://stackoverflow.com/questions/23795010/lwjgl-grabbed-mouse-debug-if-application-hangs-or-when-breakpoint-hits-with-gr/36991052#36991052 + +### ld.so dl-lookup failures + +> Inconsistency detected by ld.so: dl-lookup.c: 111: check_match: Assertion version->filename == NULL || ! _dl_name_match_p (version->filename, map)' failed! + +The process quits with this error message when attempting to load the lwjgl library under _some_ OpenJDK distributions. Please consult the distributor of your JDK about this error. It may be useful for them to refer to previous bug reports on the topic: + +* [Ubuntu #1764701](https://bugs.launchpad.net/ubuntu/+source/gcc-7/+bug/1764701) +* [Ubuntu #1838740](https://bugs.launchpad.net/ubuntu/+source/openjdk-lts/+bug/1838740) +* ✍ (if you find a well-written bug report about this for your jdk, do add it here!) + +If one of those links is to the JDK you're using, you can let them know by clicking the bug tracker's "this affects me too" link. + +In the meantime, use a different JDK. We've found [AdoptOpenJDK](https://adoptopenjdk.net/?variant=openjdk11&jvmVariant=hotspot) to work well and it can be easily installed from [IntelliJ IDEA's Download JDK](https://www.jetbrains.com/help/idea/sdk.html#manage_sdks) menu. (Hotspot, version 11.) + +### Arch/Gentoo random problems + +Both Arch and Gentoo do not include java jfx (needed for the launcher) by default when installing java. + +On Arch you need to install the `java-openjfx` package, and on Gentoo you need to use the `javafx` USE flag when compiling java. + + +xrandr is a generic linux dependency for terasology, but the cases where you have it uninstalled usually only happen on arch and gentoo. + +## Windows + +It is possible to end up getting Gradle into a fight with the Windows specific `Thumbs.db` files. If it is not an option to disable the generation of these files (relates to icon previewing) or even once after it is disabled you can clean a directory and its subdirs with one of the following commands: + +* `del /s /q /f /a:h Thumbs.db` while in the top-level directory in a plain command prompt +* `Get-ChildItem -Path . -Include Thumbs.db -Recurse -Name -Force | Remove-Item -Force` likewise, with Powershell + +Solutions sourced from https://github.com/MarcusBarnes/mik/wiki/Cookbook:-Removing-.Thumbs.db-files-from-a-directory diff --git a/docs/Troubleshooting-Player.md b/docs/Troubleshooting-Player.md new file mode 100644 index 00000000000..6d71e041624 --- /dev/null +++ b/docs/Troubleshooting-Player.md @@ -0,0 +1,18 @@ +* The most common cause for game crashes is older video cards, *especially* Intel HD Graphics on laptops. Make sure you have the very latest graphics drivers available. +* If you're using a laptop that has a discrete NVIDIA GPU and Intel HD Graphics, the game may be attempting to run on the latter, causing a crash. To make the game use the discrete GPU, + * Right-click on your desktop, select NVIDIA Control Panel. If the option doesn't show up, [install the latest NVIDIA drivers](http://www.geforce.com/drivers). + * Select *Manage 3D settings*. + * Select *Program Settings*, then navigate to wherever the Terasology executable is located and select it. + * **Note:** This used to work when Terasology shipped with a `.exe` file for Windows - we have since switched to a `.bat` which does not seem eligible for this workaround. Additionally it won't work when running the game from source (possibly unless you apply it system-wide to any execution of `java.exe` which is likely not ideal ..) - this may take some Googling and updating of this page if anybody finds better options! + * In the processor selection dropdown, choose *High-performance NVIDIA processor* and click Apply. +* You may run out of memory if your system doesn't have much available or you run the game with too little memory assigned and too high view distance. Especially with a 32-bit system or Java (has failed on even taking large screenshots in the past) + * To run with increased memory you can launch via command prompt / terminal with something like: `java -Xms128m -Xmx2048m -jar libs/Terasology.jar` which will assign a max of 2 GB (but crash with a 32-bit Java! Can't assign more than around 1.5 GB) +* You may get odd OpenAL warnings/crashes if you have an unusual audio setup. One user reported a crash after having set up a virtual audio cable for streaming purposes. That error specifically was an `IllegalStateException` over there being no OpenAL context available. + +## Proxy Settings + +**Prerequisite:** You are behind a proxy. + +**Symptoms:** You face connection issues in the Terasology Launcher or Terasology itself. + +**Solution:** Properly configure your proxy settings in your local *Java Control Panel*. For more information, please refer to https://www.java.com/en/download/help/proxy_setup.html. \ No newline at end of file diff --git a/docs/Troubleshooting.md b/docs/Troubleshooting.md new file mode 100644 index 00000000000..04cc113a28a --- /dev/null +++ b/docs/Troubleshooting.md @@ -0,0 +1,20 @@ +Not everything succeeds on the first try. When that happens check this page to see if we've covered it. + +<table align="center"> + <thead><tr> + <th width="50%"><a href="#/Troubleshooting-Player">Players</a></th> + <th width="50%"><a href="#/Troubleshooting-Developer">Developers</a></th> + </tr></thead> + <tr> + <td width="50%" align="center"><a href="Troubleshooting-Player"><img src="icons/baseline-videogame_asset-24px.svg" width=96px /></a></td> + <td width="50%" align="center"><a href="Troubleshooting-Developer"><img src="icons/baseline-bug_report-24px.svg" width=96px /></a></td> + </tr> + <tr> + <td width="50%">A crashing game is not enough entertainment? :boom: Search no more, we can help! ... at least we try :wink:</td> + <td width="50%">You're finding bugs instead of bytes? :nerd_face: This is our private stack-overflow! ... kind of :sweat_smile:</td> + </tr> +</table> + +If you encounter an issue not mentioned here try to check Google or ask us: +- [Discord](http://discord.gg/Terasology) (please be patient if nobody responds right away) +- [Support Forum](http://forum.terasology.org/forum/support.20) diff --git a/docs/Using-Locally-Developed-Libraries.md b/docs/Using-Locally-Developed-Libraries.md new file mode 100644 index 00000000000..4a73481ba51 --- /dev/null +++ b/docs/Using-Locally-Developed-Libraries.md @@ -0,0 +1,53 @@ +Terasology has close relationships with some of its dependencies, such as [TeraNUI](https://github.com/MovingBlocks/TeraNUI) for the user interface and [gestalt](https://github.com/MovingBlocks/gestalt) for its module system. + +When you're developing a feature in one of those libraries and you want to see how Terasology runs with it, that's when to make use of Gradle's [composite builds](https://docs.gradle.org/current/userguide/composite_builds.html#composite_builds) feature. + +Let's look at [TeraNUI's developer documentation](https://github.com/MovingBlocks/TeraNUI/#-development) for an example: + +> You can get the TeraNUI library as source into your local Terasology workspace as follows: +> +> `groovyw lib get TeraNUI` +> +> This will place the TeraNUI source code into `/libs/TeraNUI`. Please note that you may need to reload/refresh your gradle workspace in IntelliJ IDEA. + +`groovyw lib get` is a helpful shortcut for certain common dependencies, but know that _any_ gradle project checked out to a subdirectory of `/libs/` will be included in the composite build. + +Make sure to `git switch` in that directory to the branch of that project you're working with. + +## How do I know the library's build is being included? + +Run gradlew with the `--info` flag and look for this in the output: + +> libs/TeraNUI will be included in the composite build. + +You can also build a report of your dependencies: + +```shell +gradlew :engine:htmlDependencyReport +``` + +in which dependencies filled by subprojects or included builds will be marked with "project" like this: + +> org.terasology:gestalt-module:5.1.5 ➡ project :gestalt:gestalt-module + +Or you can check your build's list of projects on its [build scan](https://scans.gradle.com/). + + +## Terminology + +Gradle has a lot of terminology around how builds are organized. We'll break it down with some concrete examples here: + +* A **project** is defined by a [settings.gradle](https://github.com/MovingBlocks/Terasology/blob/develop/settings.gradle). Our project is defined in the top-level directory of our git repository, and it is [named `Terasology`](https://github.com/MovingBlocks/Terasology/blob/5cfb0c66f5457d16cffe1246a697314ccc1cd328/settings.gradle#L3). +* Terasology is the **root project** of a [**multi-project build**](https://docs.gradle.org/current/userguide/multi_project_builds.html). Its **subprojects** are things such as [`engine`](https://github.com/MovingBlocks/Terasology/blob/develop/engine/build.gradle) and the [facades](https://github.com/MovingBlocks/Terasology/blob/develop/facades/PC/build.gradle.kts). + + Subprojects can be separate from one another but they are always built within the _root project;_ `engine` is not meant to be built on its own. The root project may configure its subprojects and define dependencies between them. +* TeraNUI is an independent **project**. It can be built without any reference to Terasology whatsoever. When we want our Terasology build to make use of a local TeraNUI build, TeraNUI is the **included build**. The technique of combining builds this way is called a **composite build**. + + A _composite build_ is any build that involves _included builds_, there's nothing else we need to do to make it a “composite.” + +Subprojects and included builds are similar in many respects, but the root project isn't able to meddle with included builds to the same extent as it can with its own subprojects. + + +## Implementation Details + +Our [`libs/subprojects.settings.gradle`](https://github.com/MovingBlocks/Terasology/blob/develop/libs/subprojects.settings.gradle) checks each subdirectory to see if it contains files that look like a Gradle root project, and if it finds them it [adds that directory as an included build](https://docs.gradle.org/current/dsl/org.gradle.api.initialization.Settings.html#org.gradle.api.initialization.Settings:includeBuild(java.lang.Object)). diff --git a/docs/What-is-Terasology.md b/docs/What-is-Terasology.md new file mode 100644 index 00000000000..2f274f0712d --- /dev/null +++ b/docs/What-is-Terasology.md @@ -0,0 +1,48 @@ +Background for the project. + + +## History and motivation + +Back in early 2011 our founder Benjamin "begla" Glatzel wanted to research procedural terrain generation and efficient rendering techniques in Java using [LWJGL](http://lwjgl.org), curious if he could create a [Minecraft](http://www.minecraft.net)-like demo by himself. He succeeded, like quite a few others have over the years. + +The project went quiet for a few months with an occasional person checking it out until in September 2011 Anton "small-jeeper" Kireev and Rasmus "Cervator" Praestholm connected with Begla around the same time. A pitch for an actual game was made, focused on the benefits of open source and some under-served areas of Minecraft such as creature management. A [forum was created and our journey began](http://forum.terasology.org/threads/here-we-go.1)! + +Work began and improvements were made, with some goals outlined in the below section. Other contributors trickled in and we got the project infrastructure set up better. Then in July 2012 [Youtube personality Gronkh did a Let's Test video](https://youtu.be/H3qItsrpceY) that eventually crossed a million hits, melted all our servers and put us on the map. At least in Germany - lots of German players and contributors. Similar traffic spikes later have likewise gotten us, new players and contributors, always curious to see which country is next. + +We picked up the pieces (seriously, our old web host couldn't even repair our account and we had to migrate elsewhere!), picked up a bunch of new contributors, and got more serious yet about putting together a great project for people to work on. And here we are! + +As of early 2016, we are finally emerging from the shadows of stealth-development, calling our engine stable enough to release a v1.0.0 for building gameplay on, and considering our project overall alpha-ready. Over the years we've focused heavily on architecture and extensibility, with fairly little content developed. Hopefully, that's about to change with a formal release and maturity upgrade :-) + + +## Goals at a glance + +These goals were what we originally settled on to help set apart Terasology from the flood of Minecraft-inspired games that followed its smash success. A good amount of commercial successes have followed, but seemingly Terasology stands alone as a mature open source project in Java, with [Minetest](http://www.minetest.net) the one other option in C++ and Lua. + +Our horizons have broadened since, not in a small way thanks to the sheer amount of contributors with different ideas and skills. Rather than retaining the original focus, we have for better and worse ended up with a series of gameplay templates, akin to modpacks in the Minecraft world. Some still aim to set us apart while others were made by MC modders that grew weary of obfuscated code and wanted a more open experience with familiar content. + +Most importantly the final bullet below has remained true and the source of our greatest experiences: our community. Be it helping a kid in Brazil figure out how to play without knowing English or fulfilling the life dream of an elder gentleman to participate in game development we have met many great people and look forward to meeting many more! + +* Minion management akin to Dwarf Fortress or Dungeon Keeper - creatures that will have needs that take up space to provide that then in return provide you with various benefits. This helps fill out the world. +* The simple visual appeal of 3D in a voxel world like Minecraft - not too focused on providing hi-res splendor, as that inevitably leads to the high-cost race towards photorealism. At the same time, if we can jam in some fancy effects on top of that, like reflective water, so be it! :-) +* A deeper tech tree to climb, achievable mostly solo but heavily aided by minions or other players +* Crafting more focused on realistic workshops improving quality and quantity based on upgrades, specific minions, etc +* A more vivid world that's alive and changes over time, even without direct manipulation by the player +* Autonomous NPC societies that grow on their own and can both be the source of minions as well as valuable trading partners. Or be your greatest enemy... +* Various kinds of blueprinting to allow the reproduction of specific objects, tradeable with other players. Also, similar systems to designate areas as special in some fashion, like enclosing workshop areas or defining defences +* Portals to centre societies around and allow easy travel (but not the transfer of goods) between settled areas +* Meaningful (and meaningless!) statistics about your world +* Realistic simulations of world elements like liquid flow, structural support, natural growth, and the dangers of delving deep +* And maybe most importantly: Build a community around an open source project that will be able to achieve all this and more - making Terasology more than just a game + + +## Behind the name + +Why "Terasology" ? + +Like many other starting games, Begla started out with a quick name, "Blockmania" in this case, when the goal was just making a cool voxel engine. After our team grew and we set serious goals we needed a serious name that was unique and memorable. During an everyday ranting session between organizer Cervator and wordsmith Stuthulhu "Anthropology" came up as a goal for the game, but for creatures (Anthropology is specific to humans). Stuthulhu came up with "Teras" and other fancy Latin/Greek terms and it more or less just lined up with -ology perfectly + +An astute fan came up with some more details on the name after the fact: + +> On minor correction is that the word Terasology is coming from the greek word (τερατολογία) which the combination of the two greek words teras (τέρας) and logos (λόγος). In english the combination of Teras + Logos should be Teratology not Terasology. Because (Τέρας + λόγος = Τερατολογία) + +Teratology does exist as a term (see [Wikipedia](http://en.wikipedia.org/wiki/Teratology)), but we're taking a little artistic liberty with the correct formation of the word to make it our own and arrive at unique territory :D diff --git a/docs/What-we-learned-as-an-org-attending-Ludicious.mediawiki b/docs/What-we-learned-as-an-org-attending-Ludicious.mediawiki new file mode 100644 index 00000000000..0f9d00a3a0e --- /dev/null +++ b/docs/What-we-learned-as-an-org-attending-Ludicious.mediawiki @@ -0,0 +1,40 @@ +== Introduction == +On January 17 to January 21, 2018, a group of Terasology contributors attended the Game Festival [http://www.ludicious.ch/ Ludicious], in [https://www.google.com/maps/place/Alte+Kaserne/@47.37675,8.529151,15z/data=!4m5!3m4!1s0x0:0x3abf5a3228988ec7!8m2!3d47.3767502!4d8.5291509?hl=en-US Zürich], Switzerland. We had a stand-up booth in the "Sponsors" section of the festival and we had a nearly permanent presence of the duration of the festival. + +This page intends to collect what we, as an organization, learned through the experience, not so much in terms of exposure to other products and projects exhibited, but in terms of our exposure and participation to the event as a whole. + +If you attended the event, please feel free to contribute liberally to this page and help to make it a great resource for future events we might want to attend. + +== What we learned == +* the crowd tends to get bigger in the evening and over the weekend +* the whole team manning the booth the whole time is not necessary: 2-3 people at any given time are enough +* manning the booth the whole four days can be tiring: we should organize morning/afternoon shifts next time +** this was especially the case since the booth was standing only - no chairs! We should aim for seated booths in the future +** both points above also allow the reminder of the team to attend the conference or simply visit the hosting city +* our overhead poster looked too similar to MineCraft: we should make it clear we are Open Source and highly moddable +** achieving this could be tricky: MC has done so much it'll hard to showcase something visually unique. Possibly favor our low-poly models vs the full blocky nature of MC +* people who look interested but haven't made the first move can be easily approached with a friendly "Hi! Do you have any questions?" +* it is useful to discuss beforehand what key points we should share with anybody we talk to +** for example we quickly aligned on the concept "Terasology is a developer's playground" (which is true) beside the admission that we are not quite End-User friendly yet. +* university students were a good proportion of the crowd: it's good to mention GSOC to them and the opportunities it represents for both students and Terasology +* identical team T-shirts would be good. The very clearly label you as a team member for anybody who is interested in the project +** stinky t-shirts would be bad though: if we make team t-shirts we'd need one per person per day unless we can plan to rely on washing and drying facilities somewhere. +* business cards and/or leaflets with Terasology's basic information (website, github, forum, irc) are useful +** this time we had only business cards for Cervator +** next time we might want to have generic business cards (maybe with an empty side to write something, as needed) or business cards for a few more people +* estimating conference audience is hard (who is our target audience?) +** there was a lot to learn about art/style, story telling, and publishing, but … +** … not many technical sessions or dev-centric topics +* we should have a proper setup where one can try out the game +** device with decent performance and controls (mouse!) +** have a game mode/world ready/loaded any time +* Terasology videos out of YouTube are good! +** We had a couple of Ludicious-provided monitors that we didn't always use for interactive sessions. We used them to show youtube video of Terasology instead, on a long loop: people can quickly appreciate many features from Terasology that we wouldn't be able to startup or demonstrate as quickly. +** ''However''... the Terasology feed contains playsessions we held on Minecraft and we shouldn't show those. +** On top of that YouTube without login doesn't seem to auto-proceed in playlists, leading to one computer only showing the entire channel contents (which would auto-play) rather than a finely edited playlist +* Cervator tried to keep a running track of metrics on booth attendees, but this proved challenging to do in a way that would be useful / summarizable. May need to think of a better format/approach for "people metrics" +** This included some bits of feedback, but again not in a very useful format. Main two small takeaways was getting the game on Steam and having a faster-paced multiplayer setup ready to entertain multiple people at once (tricky due to space?) + +<br/> +<br/> +(...anything else?...) diff --git a/docs/Why-Terasology.md b/docs/Why-Terasology.md new file mode 100644 index 00000000000..0e322320d0f --- /dev/null +++ b/docs/Why-Terasology.md @@ -0,0 +1,105 @@ +Minecraft was a smash hit and received a massive amount of support from a community, far exceeding what it was envisioned for, which lead to lackluster support for what the community wanted as fans could not directly improve the engine. Modding became minecraft largest community, but received no official support, thus mods needed to be updated at every release. Which can cause whole game types and communities to disappear if a mod cannot remain up to date. + +Terasology's goal is to be a solid, stable, and extremely extensible voxel game engine. + + + +For example: + +0. A mod API is our main and foremost feature. For end users all module adding, updating, and downloading is handled through a simple GUI at world creations. Modules are automatically added at server join. Gameplay Templates exist for a tested and packaged experience. + +0. The creation of modules is simple, and if behavior already exists, in libraries or frameworks, no java code is needed. Modules work across many [versions](http://semver.org/), and dependencies are automatically handled. Json is used heavily. + +0. Organized, unified, but still independent. There is an official forum, IRC, and module repo. Content is unified: plugins, ResourcePacks, libraries, frameworks are just types of modules, and thus are accessed through the official module repo. However, the module repo is git based so it can be easily duplicated or forked, for decentralization. There is no login servers as each server manages the accounts themselves. Clients generate a SSH key at server join as form of Identity. However, a login module can be created for a centralized login server. + +0. A tiny core, all content should be added using modules. Freedom of gameplay + +0. Infinite height and depth, commonly known as Cubic Chunks + +0. Blocks and block shapes are separate. Once you define a shape, all blocks will have that variation. + +0. 65,000 IDs for biomes, A biome is defined per grid space, allowing for vertical biomes. + +0. A better lighting engine. Includes shaders by default, torches can give off light while placed, held, or dropped. + +0. Multithreaded. (Rendering is single threaded because of openGL, but this could change if a Rendering Wizard shows up) + +0. Open source and gratis. All currently existing modules as well, but the licenses is to be decided by the Author. + +0. Community controlled and community ran. + +0. It's in Java. + +__For Mod Developers__ + +A selection of libraries and frameworks has been created, to aid compatibility, and reduce duplication of work. Such as defining ores, common plants and how they grow, climate and weather, networking between blocks, how ores spawn etc. Modules are a good source of code reference, for seasoned and budding mod developers alike. A list of ready to use modules,libraries, and frameworks can be found in the [module repo](https://github.com/Terasology/) + +# Gameplay and Module Management + +__For the average user__ + +Switching between gameplay templates (a collection of modules, like a Minecraft modpack), is as simple as choosing between survival, creative, or hardcore in Minecraft. That is to say, it's completely handled through GUI with no external tools needed, and is managed per-world. This holds true for joining servers as well, no user setup needed. + + + + +__For the advanced user__ + +There exists a module button next to the template dropdown box, this allows for customizing any template that is currently selected. Allowing you to remove or add modules. Modules can be updated and downloaded from the [module repo](https://github.com/Terasology/) from here. Dependencies are automatically handled. Modules not in repo can be enabled here after being placed in the correct folder. + + + +# Converting a Minecraft mod to a Terasology module + +_note: this is a preliminary guide, more information can be found in the wiki_ + +First get a working [dev environment](https://github.com/MovingBlocks/Terasology/wiki/Dev-Setup) and continue on to creating or downloading a module. + + +___ +[The structure of a module](https://github.com/MovingBlocks/Terasology/wiki/Modding-Guide#structure-of-a-mod) +___ + +textures can be placed in _ModuleName/assets/blockTiles/auto_ + +where a basic block with properties inherited is created. + +[Example](https://github.com/Terasology/Minerals/tree/master/assets/blockTiles/auto) +___ + +placing texture(s) in _ModuleName/assets/blockTiles/fancy_ + +and creating a simple json file of _ModuleName/assets/blocks/BlockName.block_ + +allows properties to be set, such as the shape it comes in, its display name, categories it's in, hardness, the textures for each sides, its mass,translucent, if you can go through it, if you can target it, its tint, its prefab, debrisOnDestroy, if it waves in the wind, color source, its rotation, if you can climb it, if it drops when you break it or if you directly pick it up, if it casts a shadow etc. + +[Example](https://github.com/Terasology/Soils/tree/master/assets/blockTiles/fancy) + +[Example](https://github.com/Terasology/Soils/tree/master/assets/blocks/fancy) +___ +creating a file in _ModuleName/assets/prefabs/BlockOrItemName.prefab_ + +allows for the block or item to store data, becoming an entity. (as well as advanced data) Such as a chests ability to store items, and retain them inside when broken. Or torches needing a block to be on. Water being unbreathable, how items damage other items (like tools), the icons they use. Chests inventory being public to everyone, the sound it plays, the GUI screen it uses. + +[Example](https://github.com/Terasology/JoshariasSurvival/tree/master/assets/prefabs) + +____ + +**Module.txt** + +This is a textfile in the root of the module directory that gives module stats, and helps do the magic. + +It gives modules: an internal name, a displayed name, the Authors names, a short description, listing of dependencies so they can automatically be pulled, and so forth. + +[JoshariasSurvival](https://github.com/Terasology/JoshariasSurvival/blob/master/module.txt) , a higher level module for example. + +'Josharias Survival' the game play Is fairly complex. 'JoshariasSurvival' The module is not. JoshariasSurvival is more or less a meta package. It contains few content of its own, and actually calls Libraries and other modules as dependecies. All modules in Josharias Survival can be mixed and matched with other modules, but JoshariasSurvival automatically pull all required modules for a set up and tested play style, a gameplay template, or in Minecraft terms, a modpack. + +The __"isGameplay" : "true",__ Causes this module to show up in the Gameplay template dropdown, as it has everything in order to be played as is. Things like Mineral Library or Hunger have this set to false as they are not useful or playable on their own. + + + + + + + diff --git a/docs/_Footer.md b/docs/_Footer.md new file mode 100644 index 00000000000..e72bb537fc1 --- /dev/null +++ b/docs/_Footer.md @@ -0,0 +1,3 @@ +<p align='center'> +Found a problem on this page? Fix it! Don't wanna? [Report it!](https://github.com/MovingBlocks/Terasology/issues) +</p> \ No newline at end of file diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 00000000000..8fe7b5e1191 --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,68 @@ +- **[Home](Home.md)** +- [Contributor Quickstart Guide](Contributor-Quick-Start.md) +- [Troubleshooting](Troubleshooting.md) + +### 🕹️ Player Guides + - [What is Terasology](What-is-Terasology.md) + - [Why Terasology](Why-Terasology.md) + - [Project Overview](Project-Overview.md) + - [Setup a headless server](Setup-a-headless-server.md) + - [Troubleshooting for Players](Troubleshooting-Player.md) + - [Advanced Options](Advanced-Options.md) + +### 🤓 Development & Modding + - [Architecture](Codebase-Structure.md) + - [Using Locally Developed Libraries](Using-Locally-Developed-Libraries.md) + - [Entity Component System (ECS)](Entity-System-Architecture.md) + - [Events and Systems](Events-and-Systems.md) + - [Event Types](Event-Types.md) + - [Component Types](Component-Types.md) + - [Entities, Components and Events on the Network](Entities-Components-and-Events-on-the-Network.md) + - Module System + - [Modding API](Modding-API.md) + - [Develop Modules](Developing-Modules.md) + - [Testing Modules](Testing-Modules.md) + - [Depend on Modules](Module-Dependencies.md) + - [IO API for Modules](IO-API-for-Modules.md) + - [Module Security](Module-Security.md) + - [Renderer](Renderer.md) + - [Serialization](Serialization-Overview.md) + +### 👩🏫 Tutorial Modules + - [🔗 Overview](https://github.com/Terasology?q=Tutorial&type=source&language=) + - [🔗 Asset System](https://github.com/Terasology/TutorialAssetSystem/wiki) + - [🔗 Entity System](https://github.com/Terasology/TutorialEntitySystem/wiki) + - [🔗 Events](https://github.com/Terasology/TutorialEventsInteractions/wiki) + - [🔗 I18N](https://github.com/Terasology/TutorialI18n/wiki) + - [🔗 Multiplayer](https://github.com/Terasology/TutorialMultiplayerExtras/wiki) + - [🔗 NUI](https://github.com/Terasology/TutorialNui/wiki) + - [🔗 World Generation](https://github.com/Terasology/TutorialWorldGeneration/wiki) + +### ℹ️ Contributor Information + - [Multi-Repo Workspace](Multi-Repo-Workspace.md) + - [How to Work on a PR Efficiently](How-to-Work-on-a-PR-Efficiently.mediawiki) + - [Code Conventions](Code-Conventions.md) + - [Developing with GitHub UI / Desktop](Setting-up-a-Light-Environment.md) + - [Deal with Forks](Dealing-with-Forks.md) + - [Troubleshooting for Developers](Troubleshooting-Developer.md) + +### 📚 Guides + - [Texture Guide](Textures.md) + - [Translation Guide](Translation-Guide.md) + - [Block Shape Guide](Block-Shapes.md) + - [Block Definition Guide](Block-Definitions.md) + - [Interactive Blocks Guide](Interactive-Blocks.md) + - [Command Guide](Developing-Commands.md) + - Record & Replay + - [How to Use Record and Replay](How-to-Use-Record-and-Replay.md) + - [Replay Tests](Replay-Tests.md) + - [Record and Replay Code Details](Record-and-Replay-Code-Details.md) + - [Outreach](Outreach.md) + +### 🤖 Maintainer Guides + - [Release: Omega](Release-Omega.md) + - [Release: Modules](Release-Modules.md) + - [Build Setup](Build-Setup.md) + - [Maintenance](Maintenance.md) + - [Play Test Setup](Play-Test-Setup.md) + - [Discord Integrations](Discord-Integrations.md) diff --git a/docs/activate_addon.png b/docs/activate_addon.png new file mode 100644 index 00000000000..8e3acb28674 Binary files /dev/null and b/docs/activate_addon.png differ diff --git a/docs/architecture.png b/docs/architecture.png new file mode 100644 index 00000000000..24bfc6bef76 Binary files /dev/null and b/docs/architecture.png differ diff --git a/docs/block-shapes-TerasologyProperties.png b/docs/block-shapes-TerasologyProperties.png new file mode 100644 index 00000000000..f288bd2ee19 Binary files /dev/null and b/docs/block-shapes-TerasologyProperties.png differ diff --git a/docs/block-shapes-banner.png b/docs/block-shapes-banner.png new file mode 100644 index 00000000000..fa6a614c742 Binary files /dev/null and b/docs/block-shapes-banner.png differ diff --git a/docs/block-shapes-exploded.png b/docs/block-shapes-exploded.png new file mode 100644 index 00000000000..4aa3e5678ed Binary files /dev/null and b/docs/block-shapes-exploded.png differ diff --git a/docs/forks.png b/docs/forks.png new file mode 100644 index 00000000000..afec935b419 Binary files /dev/null and b/docs/forks.png differ diff --git a/docs/icons/baseline-bug_report-24px.svg b/docs/icons/baseline-bug_report-24px.svg new file mode 100644 index 00000000000..6b21ef1c34a --- /dev/null +++ b/docs/icons/baseline-bug_report-24px.svg @@ -0,0 +1 @@ +<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M0 0h24v24H0z" fill="none"/><path d="M20 8h-2.81c-.45-.78-1.07-1.45-1.82-1.96L17 4.41 15.59 3l-2.17 2.17C12.96 5.06 12.49 5 12 5c-.49 0-.96.06-1.41.17L8.41 3 7 4.41l1.62 1.63C7.88 6.55 7.26 7.22 6.81 8H4v2h2.09c-.05.33-.09.66-.09 1v1H4v2h2v1c0 .34.04.67.09 1H4v2h2.81c1.04 1.79 2.97 3 5.19 3s4.15-1.21 5.19-3H20v-2h-2.09c.05-.33.09-.66.09-1v-1h2v-2h-2v-1c0-.34-.04-.67-.09-1H20V8zm-6 8h-4v-2h4v2zm0-4h-4v-2h4v2z"/></svg> \ No newline at end of file diff --git a/docs/icons/baseline-videogame_asset-24px.svg b/docs/icons/baseline-videogame_asset-24px.svg new file mode 100644 index 00000000000..ca950853b83 --- /dev/null +++ b/docs/icons/baseline-videogame_asset-24px.svg @@ -0,0 +1 @@ +<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="none" d="M0 0v24h24V0H0zm23 16c0 1.1-.9 2-2 2H3c-1.1 0-2-.9-2-2V8c0-1.1.9-2 2-2h18c1.1 0 2 .9 2 2v8z"/><path d="M21 6H3c-1.1 0-2 .9-2 2v8c0 1.1.9 2 2 2h18c1.1 0 2-.9 2-2V8c0-1.1-.9-2-2-2zm-10 7H8v3H6v-3H3v-2h3V8h2v3h3v2zm4.5 2c-.83 0-1.5-.67-1.5-1.5s.67-1.5 1.5-1.5 1.5.67 1.5 1.5-.67 1.5-1.5 1.5zm4-3c-.83 0-1.5-.67-1.5-1.5S18.67 9 19.5 9s1.5.67 1.5 1.5-.67 1.5-1.5 1.5z"/></svg> \ No newline at end of file diff --git a/docs/images/Build-Setup.png b/docs/images/Build-Setup.png new file mode 100644 index 00000000000..36635271e5c Binary files /dev/null and b/docs/images/Build-Setup.png differ diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000000..f0b9a48490f --- /dev/null +++ b/docs/index.html @@ -0,0 +1,59 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="UTF-8"> + <title>Terasology - Knowledge Base + + + + + + + + + + + + + + + + + + + + + + +