├── tools ├── .gitignore ├── config-lister │ ├── src │ │ └── main │ │ │ └── java │ │ │ └── net │ │ │ └── minecraft │ │ │ └── launchwrapper │ │ │ ├── Launch.java │ │ │ ├── package-info.java │ │ │ └── LaunchClassLoader.java │ ├── README.md │ └── LICENSE.txt ├── README.md ├── code-checker │ ├── src │ │ ├── main │ │ │ ├── resources │ │ │ │ └── log4j2.xml │ │ │ └── java │ │ │ │ └── org │ │ │ │ └── spongepowered │ │ │ │ └── docs │ │ │ │ └── tools │ │ │ │ └── codeblock │ │ │ │ ├── KeywordBasedDeIndenter.java │ │ │ │ ├── KeywordRedirectingPredicate.java │ │ │ │ ├── RepeatedKeywordPredicate.java │ │ │ │ └── OnOffKeywordPredicate.java │ │ └── test │ │ │ └── java │ │ │ └── org │ │ │ └── spongepowered │ │ │ └── docs │ │ │ └── tools │ │ │ └── codeblock │ │ │ ├── KeywordBasedDeIndenterTest.java │ │ │ ├── FileCheckerTest.java │ │ │ ├── RepeatedKeywordPredicateTest.java │ │ │ ├── KeywordPartitionerTest.java │ │ │ └── KeywordRedirectingPredicateTest.java │ ├── README.md │ └── LICENSE.txt └── javadoc-checker │ ├── src │ └── main │ │ └── resources │ │ └── log4j2.xml │ ├── LICENSE.txt │ └── README.md ├── source ├── images │ ├── faq1.png │ ├── faq2.png │ ├── faq3.png │ ├── faq4.png │ ├── faq5.png │ ├── faq6.png │ ├── yklogo.png │ ├── optionals1.png │ ├── optionals2.png │ ├── optionals3.png │ ├── ore │ │ ├── help_1.png │ │ └── help_2.png │ ├── logo-spongie.png │ ├── command-features.png │ ├── ai-execution-order.png │ ├── logo-spongepowered.png │ ├── sponge-codebase-layout.png │ └── ai-execution-order.dot ├── files │ └── logs │ │ ├── SpongeForge_1.12.2-2705-7.1.0-BETA-3136_debug.log.txt │ │ └── SpongeForge_1.12.2-2705-7.1.0-BETA-3136_latest.log.txt ├── plugin │ ├── practices │ │ ├── index.rst │ │ └── bad.rst │ ├── items │ │ └── index.rst │ ├── inventory │ │ ├── index.rst │ │ ├── menu.rst │ │ ├── events.rst │ │ └── creating.rst │ ├── entities │ │ ├── index.rst │ │ └── spawning.rst │ ├── economy │ │ ├── index.rst │ │ ├── implementing.rst │ │ ├── using.rst │ │ ├── basics.rst │ │ └── practices.rst │ ├── optional │ │ └── index.rst │ ├── blocks │ │ ├── index.rst │ │ └── virtualblock.rst │ ├── text │ │ ├── index.rst │ │ └── representations │ │ │ └── index.rst │ ├── workspace │ │ └── index.rst │ ├── tutorials.rst │ ├── commands │ │ ├── index.rst │ │ ├── commandmanager.rst │ │ ├── childcommands.rst │ │ └── rawcommand.rst │ ├── placeholders │ │ └── index.rst │ ├── plugin-identifier.rst │ ├── project │ │ ├── index.rst │ │ ├── gradle.rst │ │ └── version-numbers.rst │ ├── event │ │ └── index.rst │ ├── internals │ │ ├── index.rst │ │ └── implementation.rst │ ├── offline-userplayer-data.rst │ ├── index.rst │ ├── bookview.rst │ ├── logging.rst │ ├── services.rst │ ├── database.rst │ └── metrics.rst ├── versions │ ├── index.rst │ └── legacy-versions.rst ├── server │ ├── management │ │ ├── index.rst │ │ ├── bans.rst │ │ ├── permissions.rst │ │ ├── whitelist.rst │ │ ├── exploit-patches.rst │ │ └── plugins.rst │ ├── getting-started │ │ ├── index.rst │ │ ├── port-forward.rst │ │ ├── configuration │ │ │ ├── sponge-conf.rst │ │ │ └── hocon.rst │ │ ├── implementations │ │ │ ├── spongevanilla.rst │ │ │ └── index.rst │ │ ├── jre.rst │ │ └── launch-script.rst │ ├── spongineer │ │ ├── index.rst │ │ └── bugreport.rst │ └── index.rst ├── ore │ ├── routes │ │ ├── download.rst │ │ ├── project-version.rst │ │ ├── project.rst │ │ ├── user.rst │ │ ├── list-versions.rst │ │ └── deploy-version.rst │ ├── index.rst │ └── security.rst ├── contributing │ ├── implementation │ │ ├── debugging │ │ │ ├── tools.rst │ │ │ ├── issues.rst │ │ │ ├── faq.rst │ │ │ ├── more.rst │ │ │ ├── index.rst │ │ │ └── testing.rst │ │ ├── index.rst │ │ ├── git-implementation.rst │ │ └── pr.rst │ ├── porting.rst │ ├── index.rst │ └── guidelines.rst ├── preparing │ ├── index.rst │ ├── ide.rst │ ├── jdk.rst │ ├── text.rst │ └── git.rst └── about │ ├── future.rst │ ├── index.rst │ ├── license.rst │ ├── posting.rst │ ├── assets.rst │ └── introduction.rst ├── renovate.json ├── package.json ├── requirements.txt ├── crowdin.yaml ├── CONTRIBUTING.md ├── .travis.yml ├── deployment └── generate-dockerfile.sh ├── .gitattributes ├── Dockerfile ├── README.md ├── gulpfile.js └── .gitignore /tools/.gitignore: -------------------------------------------------------------------------------- 1 | !src/ -------------------------------------------------------------------------------- /source/images/faq1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/faq1.png -------------------------------------------------------------------------------- /source/images/faq2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/faq2.png -------------------------------------------------------------------------------- /source/images/faq3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/faq3.png -------------------------------------------------------------------------------- /source/images/faq4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/faq4.png -------------------------------------------------------------------------------- /source/images/faq5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/faq5.png -------------------------------------------------------------------------------- /source/images/faq6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/faq6.png -------------------------------------------------------------------------------- /source/images/yklogo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/yklogo.png -------------------------------------------------------------------------------- /source/images/optionals1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/optionals1.png -------------------------------------------------------------------------------- /source/images/optionals2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/optionals2.png -------------------------------------------------------------------------------- /source/images/optionals3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/optionals3.png -------------------------------------------------------------------------------- /source/images/ore/help_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/ore/help_1.png -------------------------------------------------------------------------------- /source/images/ore/help_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/ore/help_2.png -------------------------------------------------------------------------------- /source/images/logo-spongie.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/logo-spongie.png -------------------------------------------------------------------------------- /source/images/command-features.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/command-features.png -------------------------------------------------------------------------------- /source/images/ai-execution-order.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/ai-execution-order.png -------------------------------------------------------------------------------- /source/images/logo-spongepowered.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/logo-spongepowered.png -------------------------------------------------------------------------------- /source/images/sponge-codebase-layout.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/images/sponge-codebase-layout.png -------------------------------------------------------------------------------- /source/files/logs/SpongeForge_1.12.2-2705-7.1.0-BETA-3136_debug.log.txt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/files/logs/SpongeForge_1.12.2-2705-7.1.0-BETA-3136_debug.log.txt -------------------------------------------------------------------------------- /source/files/logs/SpongeForge_1.12.2-2705-7.1.0-BETA-3136_latest.log.txt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SpongePowered/SpongeDocs/HEAD/source/files/logs/SpongeForge_1.12.2-2705-7.1.0-BETA-3136_latest.log.txt -------------------------------------------------------------------------------- /tools/config-lister/src/main/java/net/minecraft/launchwrapper/Launch.java: -------------------------------------------------------------------------------- 1 | package net.minecraft.launchwrapper; 2 | 3 | public class Launch { 4 | 5 | public static LaunchClassLoader classLoader = new LaunchClassLoader(); 6 | 7 | } 8 | -------------------------------------------------------------------------------- /renovate.json: -------------------------------------------------------------------------------- 1 | { 2 | "$schema": "https://docs.renovatebot.com/renovate-schema.json", 3 | "extends": [ 4 | "local>SpongePowered/.github:renovate-config" 5 | ], 6 | "labels": [ 7 | "dependencies" 8 | ], 9 | "ignorePaths": ["tools/**"] 10 | } 11 | -------------------------------------------------------------------------------- /tools/config-lister/src/main/java/net/minecraft/launchwrapper/package-info.java: -------------------------------------------------------------------------------- 1 | /** 2 | * Helper code to avoid NoClassDefFoundError in 3 | * {@link org.spongepowered.common.config.category.WorldCategory#WorldCategory()}. 4 | */ 5 | package net.minecraft.launchwrapper; 6 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "SpongeDocs", 3 | "version": "0.0.2", 4 | "private": true, 5 | "type": "module", 6 | "devDependencies": { 7 | "browser-sync": "3.0.4", 8 | "del": "8.0.0", 9 | "gulp": "5.0.1", 10 | "plugin-error": "2.0.1" 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /tools/config-lister/src/main/java/net/minecraft/launchwrapper/LaunchClassLoader.java: -------------------------------------------------------------------------------- 1 | package net.minecraft.launchwrapper; 2 | 3 | public class LaunchClassLoader { 4 | 5 | public byte[] getClassBytes(final String name) { 6 | return null; 7 | } 8 | 9 | } 10 | -------------------------------------------------------------------------------- /source/plugin/practices/index.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | Practices 3 | ========= 4 | 5 | This section describes some best practices that should be followed and some bad practices that should be avoided. 6 | 7 | .. toctree:: 8 | :maxdepth: 2 9 | :titlesonly: 10 | 11 | best 12 | bad 13 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | sphinx==4.5.0 2 | sphinx-intl==2.1.0 3 | sphinx-JDLinker==2.0.1 4 | sponge-docs-theme==1.1.0 5 | sphinxcontrib-applehelp==1.0.4 6 | sphinxcontrib.devhelp==1.0.2 7 | sphinxcontrib.htmlhelp==2.0.0 8 | sphinxcontrib.qthelp==1.0.3 9 | sphinxcontrib.serializinghtml==1.1.5 10 | standard-imghdr==3.13.0 11 | -------------------------------------------------------------------------------- /source/versions/index.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | Versioning Policy 3 | ================= 4 | 5 | This section describes how Sponge manages versions. 6 | 7 | Contents 8 | ======== 9 | 10 | .. toctree:: 11 | :maxdepth: 2 12 | :titlesonly: 13 | 14 | versioning 15 | filenames 16 | legacy-versions 17 | -------------------------------------------------------------------------------- /source/plugin/items/index.rst: -------------------------------------------------------------------------------- 1 | ===== 2 | Items 3 | ===== 4 | 5 | Items are a fundamental feature of Minecraft and plugins. This section shows some basic usage examples and how to 6 | create your own items. 7 | 8 | 9 | 10 | .. toctree:: 11 | :maxdepth: 2 12 | :titlesonly: 13 | 14 | usage 15 | creating 16 | -------------------------------------------------------------------------------- /source/server/management/index.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | Server Management 3 | ================= 4 | 5 | Contents 6 | ======== 7 | 8 | .. toctree:: 9 | :maxdepth: 2 10 | :titlesonly: 11 | 12 | whitelist 13 | bans 14 | permissions 15 | plugins 16 | exploit-patches 17 | performance-tweaks 18 | -------------------------------------------------------------------------------- /source/server/getting-started/index.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Getting Started 3 | =============== 4 | 5 | Contents 6 | ======== 7 | 8 | .. toctree:: 9 | :maxdepth: 2 10 | :titlesonly: 11 | 12 | jre 13 | migrating 14 | implementations/index 15 | launch-script 16 | port-forward 17 | bungeecord 18 | configuration/index 19 | -------------------------------------------------------------------------------- /source/server/spongineer/index.rst: -------------------------------------------------------------------------------- 1 | ============================= 2 | Becoming an Expert Spongineer 3 | ============================= 4 | 5 | Contents 6 | ======== 7 | 8 | .. toctree:: 9 | :maxdepth: 2 10 | :titlesonly: 11 | 12 | commands 13 | troubleshooting 14 | logs 15 | debugging 16 | incompatible 17 | bugreport 18 | properties 19 | -------------------------------------------------------------------------------- /source/ore/routes/download.rst: -------------------------------------------------------------------------------- 1 | ======================== 2 | Download Project Version 3 | ======================== 4 | 5 | **GET /api/v1/projects/:pluginId/versions/:version/download** 6 | 7 | Returns a file stream for the specified version within the specified project. The ``:version`` parameter may be replaced 8 | with ``recommended`` to download the project's current recommended version. 9 | -------------------------------------------------------------------------------- /tools/README.md: -------------------------------------------------------------------------------- 1 | Docs-Tools 2 | ========== 3 | 4 | This package contains a number of tools that help maintaining the docs. 5 | 6 | * [Javadoc-Checker](javadoc-checker) - Checks imports and javadoc-references 7 | * [Code-Checker](code-checker) - Extracts code blocks and wraps them in proper classes 8 | * [Config-Lister](config-lister) - A library that generates a page that explains the configuration options in Sponge. 9 | -------------------------------------------------------------------------------- /crowdin.yaml: -------------------------------------------------------------------------------- 1 | project_id_env: CROWDIN_PROJECT_ID 2 | api_token_env: CROWDIN_TOKEN 3 | base_path: . 4 | base_url: 'https://spongepowered.crowdin.com' 5 | 6 | files: 7 | - source: '/build/locale/**/*.pot' 8 | translation: '/locale/%locale_with_underscore%/LC_MESSAGES/**/%file_name%.po' 9 | 10 | languages_mapping: 11 | locale_with_underscore: 12 | # Pseudo-language used for In-Context Localization 13 | lol: translate 14 | -------------------------------------------------------------------------------- /source/plugin/inventory/index.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | Inventory 3 | ========= 4 | 5 | Inventories hold items. 6 | This section show how to interact with inventories 7 | 8 | Items are a fundamental feature of Minecraft and plugins. This section shows some basic usage examples and how to 9 | create your own items. 10 | 11 | 12 | .. toctree:: 13 | :maxdepth: 2 14 | :titlesonly: 15 | 16 | usage 17 | creating 18 | menu 19 | events 20 | 21 | -------------------------------------------------------------------------------- /tools/code-checker/src/main/resources/log4j2.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | -------------------------------------------------------------------------------- /tools/javadoc-checker/src/main/resources/log4j2.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | -------------------------------------------------------------------------------- /source/contributing/implementation/debugging/tools.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Debugging Tools 3 | =============== 4 | 5 | .. note:: 6 | 7 | This page has not been filled yet by our Documentation Team. If you feel like you can help, you can do so on `our 8 | GitHub repository `_. Also see the `related GitHub Issue 9 | `_ for more information on what is required. 10 | -------------------------------------------------------------------------------- /source/plugin/entities/index.rst: -------------------------------------------------------------------------------- 1 | ======== 2 | Entities 3 | ======== 4 | 5 | .. warning:: 6 | These docs were written for SpongeAPI 7 and are likely out of date. 7 | `If you feel like you can help update them, please submit a PR! `__ 8 | 9 | Entities are a huge part of Minecraft, and SpongeAPI in general. 10 | 11 | .. toctree:: 12 | :maxdepth: 2 13 | :titlesonly: 14 | 15 | spawning 16 | modifying 17 | ai 18 | custom-ai 19 | -------------------------------------------------------------------------------- /source/preparing/index.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | Preparing for Development 3 | ========================= 4 | 5 | The articles in this section explain how to set up your development environment. 6 | This is intended for developers who wish to develop plugins with SpongeAPI and for developers who wish to 7 | contribute to the Sponge project. 8 | 9 | Contents 10 | ======== 11 | 12 | .. toctree:: 13 | :maxdepth: 2 14 | :titlesonly: 15 | 16 | jdk 17 | ide 18 | text 19 | git 20 | -------------------------------------------------------------------------------- /source/contributing/implementation/debugging/issues.rst: -------------------------------------------------------------------------------- 1 | ============================ 2 | Common Issues When Debugging 3 | ============================ 4 | 5 | .. note:: 6 | 7 | This page has not been filled yet by our Documentation Team. If you feel like you can help, you can do so on `our 8 | GitHub repository `_. Also see the `related GitHub Issue 9 | `_ for more information on what is required. 10 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | **SpongeDocs** is the official repository of documentation for the Sponge Poject. 2 | 3 | The best way to become familiar with the Docs is to visit them, and read them in your language of choice: 4 | 5 | https://docs.spongepowered.org/ 6 | 7 | If you want to help the SpongeDocs, there is a page of the Docs that explains how you can assist: 8 | 9 | https://docs.spongepowered.org/stable/en/contributing/spongedocs.html 10 | 11 | Contact SpongeDocs staff on GitHub / Discord / IRC / Sponge Forums if you have any further questions. 12 | -------------------------------------------------------------------------------- /source/plugin/economy/index.rst: -------------------------------------------------------------------------------- 1 | ======= 2 | Economy 3 | ======= 4 | 5 | Sponge provides an Economy API that unifies all economy plugins under one single API. The API can be used by both 6 | economy plugins providing the API, and other plugins using the API (i.e. shop plugins). This allows for all 7 | plugins that require an economy to work with any Sponge economy plugin. 8 | 9 | Contents 10 | ======== 11 | 12 | .. toctree:: 13 | :maxdepth: 2 14 | :titlesonly: 15 | 16 | basics 17 | using 18 | practices 19 | implementing 20 | -------------------------------------------------------------------------------- /source/plugin/optional/index.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | Optionals 3 | ========= 4 | 5 | ``Optional``\ s are a feature widely used in SpongeAPI. This section tries to explain why we need them and how 6 | they're used. If you already know why we use ``Optional``\ s, just head directly to the :doc:`usage` section. If you're 7 | unsure what they are, what they do and why we need them, then :doc:`basic` should be the first chapter to read. 8 | 9 | Contents 10 | ======== 11 | 12 | .. toctree:: 13 | :maxdepth: 2 14 | :titlesonly: 15 | 16 | basic 17 | usage 18 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | sudo: false 2 | 3 | language: python 4 | python: 3.6 5 | 6 | before_script: source travis-prepare 7 | script: sphinx-build -W -d build/doctrees source build/html 8 | 9 | # Deploy PR preview if this build is a pull request 10 | after_success: '[[ "$TRAVIS_PULL_REQUEST" != "false" ]] && pr-deploy' 11 | 12 | env: 13 | global: 14 | - secure: "S4ZpYUToi3L0Stus5/7eCsr634zby+Y/is1CZBX3VLHTQ8XZNr/4SIeEcd6foUTEvY+nAiQnpXoEVph8kqZjp3ATVJbyV4qK0HTSCEm+TAG0Xk/pMixvb8wx7zsQN94Z3KDTCG2UKcmIMUU2EYMRlhCl+RVBU5DxOPO+4TOFVQ0=" 15 | 16 | notifications: 17 | email: false 18 | -------------------------------------------------------------------------------- /source/images/ai-execution-order.dot: -------------------------------------------------------------------------------- 1 | digraph G { 2 | 3 | tick -> shouldUpdate[label="Inactive"]; 4 | tick -> continueUpdating[label="Active"]; 5 | shouldUpdate -> start[label=" true"]; 6 | continueUpdating -> update[label="true"]; 7 | continueUpdating -> reset[label="false"]; 8 | 9 | tick [shape=Mdiamond, label="ai-ticking"]; 10 | start[label="start()"]; 11 | shouldUpdate[label="shouldUpdate() : boolean"]; 12 | continueUpdating[label="continueUpdating() : boolean"]; 13 | update[label="update()"]; 14 | reset[label="reset()"]; 15 | 16 | } -------------------------------------------------------------------------------- /source/plugin/blocks/index.rst: -------------------------------------------------------------------------------- 1 | ====== 2 | Blocks 3 | ====== 4 | 5 | Blocks are the very foundation of every Minecraft world, the element that makes Minecraft Minecraft-y. This section 6 | details how information about a block's type and attributes are read and set via SpongeAPI, what tile entities are 7 | and how they can be tamed to behave exactly like you want them to. 8 | 9 | 10 | Contents 11 | ======== 12 | 13 | .. toctree:: 14 | :maxdepth: 2 15 | :titlesonly: 16 | 17 | concepts 18 | accessing 19 | modifying 20 | blockentities 21 | virtualblock 22 | -------------------------------------------------------------------------------- /source/contributing/porting.rst: -------------------------------------------------------------------------------- 1 | ================================= 2 | Porting Sponge to Other Platforms 3 | ================================= 4 | 5 | Currently, two official Sponge implementations are being developed: 6 | 7 | * SpongeForge, a coremod for Minecraft Forge 8 | * SpongeVanilla, based on the Vanilla Minecraft Server 9 | 10 | If you plan to implement SpongeAPI on another platform, please make sure to provide all needed dependencies. 11 | 12 | Expected Dependencies 13 | ===================== 14 | 15 | Plugin developers expect the following dependencies to be bundled with implementations: 16 | 17 | * Guava 18 | * Guice 19 | * Gson 20 | -------------------------------------------------------------------------------- /tools/config-lister/README.md: -------------------------------------------------------------------------------- 1 | Config-Lister 2 | ============= 3 | 4 | A library that generates a page that explains the configuration options in Sponge. 5 | 6 | Requirements 7 | ------------ 8 | 9 | * Java 8 10 | * Maven 3.5 11 | 12 | Usage 13 | ----- 14 | 15 | 1. Update the SpongeCommon dependency to the latest recommended release in the pom. 16 | 2. And then run the generated jar file: 17 | 18 | ````bash 19 | java -jar config-lister.jar 20 | ```` 21 | 22 | or run the maven command: 23 | 24 | ````bash 25 | mvn exec:java 26 | ```` 27 | 28 | 3. Copy the output from your console into `source/server/getting-started/configuration/sponge-conf.rst` 29 | and update the reference to the SpongeCommon version on that page 30 | -------------------------------------------------------------------------------- /source/about/future.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | Plans for the Future 3 | ==================== 4 | 5 | There is a lot we would like to do. Specifically: 6 | 7 | * If Mojang releases an official modding API, we are interested in building SpongeAPI on top of Mojang's modding 8 | API so Sponge plugins will work on both. 9 | * We may support client-side Sponge mods that could perform a variety of functions related to the client. 10 | 11 | There are also some things we have decided not to do: 12 | 13 | * We will not support Bukkit plugins natively. 14 | * We will not send Forge mods from the server to the client because of security concerns. 15 | * We will not develop implementations using other programming languages, but we encourage others to do so. Our focus is 16 | on Java. 17 | -------------------------------------------------------------------------------- /deployment/generate-dockerfile.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env sh 2 | 3 | REGISTRY=ghcr.io 4 | IMAGE_NAME=spongepowered/spongedocs 5 | touch deployment/Dockerfile 6 | 7 | echo "FROM $REGISTRY/spongepowered/sponge-docs-theme:latest as homepage" >> deployment/Dockerfile 8 | i=0 9 | for version in $VERSIONS; do 10 | echo "FROM $REGISTRY/$IMAGE_NAME:$version as builder-$i" >> deployment/Dockerfile 11 | i=$(( i + 1 )) 12 | done 13 | 14 | echo "FROM nginx:1.19.4-alpine" >> deployment/Dockerfile 15 | echo "COPY --from=homepage /usr/share/nginx/html /usr/share/nginx/html" >> deployment/Dockerfile 16 | 17 | i=0 18 | for version in $VERSIONS; do 19 | echo "COPY --from=builder-$i /usr/share/nginx/html/$version /usr/share/nginx/html/$version" >> deployment/Dockerfile 20 | i=$(( i + 1 )) 21 | done 22 | -------------------------------------------------------------------------------- /source/contributing/implementation/index.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | Developing Sponge 3 | ================= 4 | 5 | These sections describe the best way to approach the project when you're intending to develop Sponge itself. It is 6 | mandatory to be familiar with :doc:`git <../howtogit>` and our :doc:`codestyle`. Basic knowledge of 7 | :doc:`/about/structure` is also very helpful. 8 | 9 | If you want to join us in creating Sponge, head straight over to the :doc:`pr` page. 10 | 11 | Contents 12 | ======== 13 | 14 | .. toctree:: 15 | :maxdepth: 2 16 | :titlesonly: 17 | 18 | codestyle 19 | git-implementation 20 | pr 21 | debugging/index 22 | mixins 23 | datamanipulator 24 | 25 | 26 | .. tip:: 27 | 28 | Video tutorials by trusted developers will be featured here when available. 29 | -------------------------------------------------------------------------------- /source/plugin/inventory/menu.rst: -------------------------------------------------------------------------------- 1 | .. _inventory-menu: 2 | 3 | ============== 4 | Inventory Menu 5 | ============== 6 | 7 | InventoryMenu is Helper and wrapper around ViewableInventories/Containers. 8 | 9 | ViewableInventory can be used in menus to allow low level callbacks on the open container instead of using events. 10 | 11 | You can swap out the ViewableInventory of an open menu. 12 | If the ViewableInventory has the same ContainerType this can even happen without closing it on the client side. 13 | 14 | Registering `InventoryCallbackHandler` s provides low level callbacks for actions with the container. 15 | 16 | Setting the container title. 17 | Setting readonly mode. 18 | 19 | .. code-block:: java 20 | 21 | public static void callbacks() { 22 | TODO think up some nice callback examples 23 | } 24 | -------------------------------------------------------------------------------- /source/about/index.rst: -------------------------------------------------------------------------------- 1 | ======================== 2 | About the Sponge Project 3 | ======================== 4 | 5 | The articles in this section explain the purpose and goals of the Sponge project. Think of this section as an extended 6 | FAQ. Rules and guidelines for the Sponge communication channels, including Sponge Forums, IRC Channels and subreddit, 7 | and a Glossary of common terms, are also provided below. 8 | 9 | If you refuse to read this section, Spongie will be very upset. Don't make Spongie upset! 10 | 11 | Contents 12 | ======== 13 | 14 | .. toctree:: 15 | :maxdepth: 2 16 | :titlesonly: 17 | 18 | introduction 19 | faq 20 | structure 21 | future 22 | license 23 | posting 24 | rules 25 | tos 26 | privacy 27 | staff 28 | glossary 29 | assets 30 | history 31 | -------------------------------------------------------------------------------- /source/server/management/bans.rst: -------------------------------------------------------------------------------- 1 | ============= 2 | Managing Bans 3 | ============= 4 | 5 | Minecraft, and consequently Sponge, has simple ban management to prevent unwanted users from joining your server. 6 | 7 | 8 | The ``/ban [reason]`` command is a native Minecraft server function that bans player *name*. The complete list 9 | of banned players is available using the command ``/banlist players`` 10 | 11 | 12 | It is also possible to ban any connections from a given IP address using ``/banip [reason]``. The complete 13 | list of banned IP addresses is available using the command ``/banlist ips`` 14 | 15 | 16 | A ban can be reversed using the command ``/pardon `` or ``/pardon `` 17 | 18 | 19 | More information on Bans can be found at the `Minecraft Wiki `_. 20 | -------------------------------------------------------------------------------- /source/plugin/text/index.rst: -------------------------------------------------------------------------------- 1 | ==== 2 | Text 3 | ==== 4 | 5 | The Text API is used to create formatted text, which can be sent to players in chat messages and be used in 6 | places such as in books and on signs. 7 | 8 | Sponge uses the `Adventure`_ library as its text implementation. 9 | Since Adventure already provides docs on how to create and manipulate text objects, 10 | we will supply you with Sponge-specific guides and a basic introduction. 11 | 12 | Pagination, the process of splitting content (such as lists of Text) into discrete pages, will also be discussed in 13 | this section. 14 | 15 | Contents 16 | ======== 17 | 18 | .. toctree:: 19 | :maxdepth: 2 20 | :titlesonly: 21 | 22 | Adventure Docs (external) 23 | text 24 | representations/index 25 | pagination 26 | 27 | .. _Adventure: https://docs.papermc.io/adventure/ 28 | -------------------------------------------------------------------------------- /source/plugin/workspace/index.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | Setting Up Your Workspace 3 | ========================= 4 | 5 | This section shows the basic setup for your IDE, to get yourself ready to develop Sponge plugins. 6 | 7 | Currently we only provide documentation for the two most popular Java IDEs, IntelliJ_ and Eclipse_, 8 | but there are many other methods for developing Sponge plugins. Some choose to use Netbeans_ and 9 | others choose to simply use text editors such as `VS Code`_, Atom_, and `Sublime Text`_. 10 | 11 | Contents 12 | ======== 13 | 14 | .. toctree:: 15 | :maxdepth: 2 16 | :titlesonly: 17 | 18 | idea 19 | eclipse 20 | 21 | .. _IntelliJ: https://www.jetbrains.com/idea/ 22 | .. _Eclipse: https://www.eclipse.org/ 23 | .. _Netbeans: https://netbeans.org/ 24 | .. _`VS Code`: https://code.visualstudio.com/ 25 | .. _Atom: https://atom.io/ 26 | .. _`Sublime Text`: https://www.sublimetext.com/ 27 | -------------------------------------------------------------------------------- /source/plugin/tutorials.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | Tutorials 3 | ========= 4 | 5 | .. warning:: 6 | These docs were written for SpongeAPI 7 and are likely out of date. 7 | `If you feel like you can help update them, please submit a PR! `__ 8 | 9 | This section is a repository of links to instructional videos about sponge plugin development, prepared by trusted 10 | developers. We hope that these will guide you to great heights in sponge plugin development. 11 | 12 | 13 | Intellij IDEA 14 | ============= 15 | 16 | Long-time Sponge Contributor Sibomots has prepared a series of instructional videos using Intellij IDEA. 17 | 18 | * `Setting up SpongeForge with IntelliJ IDEA `__ 19 | 20 | More information and discussion on these topics can be found on the Sponge Forums. 21 | 22 | 23 | We hope there are many more to come! 24 | -------------------------------------------------------------------------------- /source/server/index.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | Creating a Server 3 | ================= 4 | 5 | The articles in this section explain how to create and run a server powered by an implementation of SpongeAPI. 6 | 7 | If you're a user who wishes to create a new server using an implementation of Sponge or migrate an 8 | existing server to an implementation of Sponge, this is for you. Plugin developers may also be interested in the 9 | articles contained within this section - test servers can be useful for plugin development. 10 | 11 | .. note:: 12 | 13 | We attempt to be implementation-agnostic when possible, meaning that instructions generally aren't specific to one 14 | implementation of SpongeAPI. Nonetheless, mistakes can happen. 15 | 16 | Contents 17 | ======== 18 | 19 | .. toctree:: 20 | :maxdepth: 2 21 | :titlesonly: 22 | 23 | quickstart 24 | getting-started/index 25 | management/index 26 | spongineer/index 27 | -------------------------------------------------------------------------------- /tools/code-checker/README.md: -------------------------------------------------------------------------------- 1 | Code-Checker 2 | ============ 3 | 4 | A helper to extract the code blocks from the docs for the analysis, whether the code still compiles and is up to date. 5 | 6 | Requirements 7 | ------------ 8 | 9 | * Java 10 10 | * Maven 3.5 11 | 12 | Usage 13 | ----- 14 | 15 | This application takes two optional parameters: `[path_to_SpongeDocs/sources [path_for_generated_sources]]` 16 | 17 | There a two variants to run this project. 18 | 19 | ### Direct 20 | 21 | The simplest one is just run the following command in the command line: 22 | 23 | ````bash 24 | mvn 25 | ```` 26 | 27 | This way assumes it is executed from within the SpongeDocs repo. 28 | 29 | You can also pass command line arguments to this like: 30 | 31 | ````bash 32 | mvn -Dexec.args="../../source target/generated-sources/codeblocks" 33 | ```` 34 | 35 | ### Stand-alone 36 | 37 | Or you can build the jar and then run it: 38 | 39 | ````bash 40 | mvn clean package 41 | java -jar code-checker-x.y.z.jar 42 | ```` 43 | -------------------------------------------------------------------------------- /source/preparing/ide.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | Installing an IDE 3 | ================= 4 | 5 | 6 | What is an IDE? 7 | =============== 8 | 9 | The installation of an IDE - also known as an integrated development environment - is recommended for developing Sponge 10 | plugins and/or working on Sponge itself. An IDE auto-completes names and notifies you of errors, such as mismatched 11 | braces, in your code. 12 | 13 | Which one should I choose? 14 | ========================== 15 | 16 | Every IDE has its pros and cons, and there is no single best IDE for Sponge development. The IDE you choose to use is 17 | largely a matter of personal preference. That being said, it is worth mentioning that `IntelliJ IDEA Community Edition 18 | `__ is fairly popular amongst a majority of the core Sponge team. 19 | 20 | Downloads 21 | ========= 22 | 23 | * `IntelliJ IDEA `__ 24 | * `Eclipse `__ 25 | * `NetBeans `__ 26 | -------------------------------------------------------------------------------- /source/plugin/commands/index.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Plugin Commands 3 | =============== 4 | 5 | .. javadoc-import:: 6 | org.spongepowered.api.command.Command.Raw 7 | org.spongepowered.api.command.Command.Parameterized 8 | 9 | .. tip:: 10 | 11 | Since the Command API makes use of the Component API, make sure you 12 | read `Component `_ first 13 | 14 | There are two different API's to create commands in Sponge: 15 | The :javadoc:`Command.Parameterized` builder and the :javadoc:`Command.Raw` interface. 16 | 17 | The most comfortable way to create a new command is the ``Command.Parameterized`` builder, which will be detailed in 18 | this section. It supports child commands and takes advantage of Minecraft's Brigadier system. 19 | 20 | Alternatively, you can use ``Command.Raw``, a lower-level interface which you can extend your own command system onto. 21 | 22 | Contents 23 | ======== 24 | 25 | .. toctree:: 26 | :maxdepth: 2 27 | :titlesonly: 28 | 29 | commandbuilding 30 | argumentparsing 31 | childcommands 32 | commandmanager 33 | rawcommand -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | #common settings that generally should always be used with your language specific settings 2 | 3 | # Auto detect text files and perform LF normalization 4 | # http://davidlaing.com/2012/09/19/customise-your-gitattributes-to-become-a-git-ninja/ 5 | * text=auto 6 | 7 | # 8 | # The above will handle all files NOT found below 9 | # 10 | 11 | # Documents 12 | *.doc diff=astextplain 13 | *.DOC diff=astextplain 14 | *.docx diff=astextplain 15 | *.DOCX diff=astextplain 16 | *.dot diff=astextplain 17 | *.DOT diff=astextplain 18 | *.pdf diff=astextplain 19 | *.PDF diff=astextplain 20 | *.rtf diff=astextplain 21 | *.RTF diff=astextplain 22 | *.md text 23 | *.rst text 24 | *.adoc text 25 | *.textile text 26 | *.mustache text 27 | *.csv text 28 | *.tab text 29 | *.tsv text 30 | *.sql text 31 | 32 | # Graphics 33 | *.png binary 34 | *.jpg binary 35 | *.jpeg binary 36 | *.gif binary 37 | *.tif binary 38 | *.tiff binary 39 | *.ico binary 40 | # SVG treated as an asset (binary) by default. If you want to treat it as text, 41 | # comment-out the following line and uncomment the line after. 42 | #*.svg binary 43 | *.svg text 44 | *.eps binary 45 | -------------------------------------------------------------------------------- /source/plugin/placeholders/index.rst: -------------------------------------------------------------------------------- 1 | ============ 2 | Placeholders 3 | ============ 4 | 5 | .. warning:: 6 | These docs were written for SpongeAPI 7 and are likely out of date. 7 | `If you feel like you can help update them, please submit a PR! `__ 8 | 9 | .. javadoc-import:: 10 | net.kyori.adventure.text.Component 11 | 12 | A common task for chat plugins is to provide and consume placeholders, tokens that map to :javadoc:`Component` based on 13 | context. For example, a "name" placeholder may return a player's name, or a "balance" placeholder may return the value 14 | of a player's default account. 15 | 16 | Sponge provides a simple Placeholder API that provides a registry for placeholders, as well a structure to parse them. 17 | This allows for a common way for plugins to provide their own placeholders without requiring a specific placeholder 18 | library being installed. 19 | 20 | .. note:: 21 | The Sponge placeholder API does not provide a way to parse entire strings that contain tokens. 22 | 23 | Contents 24 | ======== 25 | 26 | .. toctree:: 27 | :maxdepth: 2 28 | :titlesonly: 29 | 30 | creatingtokens 31 | retrievingtext 32 | -------------------------------------------------------------------------------- /source/contributing/implementation/debugging/faq.rst: -------------------------------------------------------------------------------- 1 | ========================== 2 | Frequently Asked Questions 3 | ========================== 4 | 5 | .. note:: 6 | 7 | This page is not complete. If you feel like you can help, you can do so on `our GitHub repository 8 | `_. Also see the `related GitHub Issue 9 | `_ for more information on what is required. 10 | 11 | Installing Sponge 12 | ----------------- 13 | 14 | 15 | Configuring Sponge 16 | ------------------ 17 | 18 | 19 | GIT 20 | --- 21 | 22 | 23 | IntelliJ 24 | -------- 25 | 26 | - How do I fix my run configurations when a main class is not specified? 27 | 28 | When in the ``Edit Configurations...`` window, select a module that has ``.main`` in its name in the ``Use classpath 29 | of module:`` dropdown list. Click ``Apply``. 30 | 31 | - Why does my SpongeVanilla workspace not have a ``genIntelliJRuns`` task? 32 | 33 | This is by design. See `VanillaGradle doesn't have genIntelliJRuns 34 | `_ in Sponge Forums for 35 | details. 36 | 37 | -------------------------------------------------------------------------------- /source/server/getting-started/port-forward.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Port Forwarding 3 | =============== 4 | 5 | If you are running your Sponge server from your home, it is necessary to set up Port Forwarding on your modem or router 6 | in order for other people to connect. 7 | 8 | .. warning:: 9 | 10 | Ensure you take the necessary precautions when port forwarding, because it can be insecure. 11 | 12 | Minecraft, and thus Sponge, uses port 25565 by default. Therefore, port 25565 must be port forwarded to the internal 13 | IP address of your computer. UDP and TCP are the protocols that must be forwarded. 14 | 15 | .. tip:: 16 | 17 | You may change which port is used by editing the appropriate key in your 18 | `server.properties `__. 19 | 20 | Port Forwarding can be performed through your router's administrator panel. If you do not know how to navigate to your 21 | router's administration panel, conduct an internet search for specific instructions on port forwarding for your router. 22 | The instructions are typically different for every router. 23 | 24 | If it is preferable to have your server online upon starting up, you may need to port forward your hardware. 25 | -------------------------------------------------------------------------------- /tools/code-checker/LICENSE.txt: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) SpongePowered 4 | Copyright (c) contributors 5 | 6 | Permission is hereby granted, free of charge, to any person obtaining a copy 7 | of this software and associated documentation files (the "Software"), to deal 8 | in the Software without restriction, including without limitation the rights 9 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 | copies of the Software, and to permit persons to whom the Software is 11 | furnished to do so, subject to the following conditions: 12 | 13 | The above copyright notice and this permission notice shall be included in 14 | all copies or substantial portions of the Software. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 22 | THE SOFTWARE. -------------------------------------------------------------------------------- /tools/javadoc-checker/LICENSE.txt: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) SpongePowered 4 | Copyright (c) contributors 5 | 6 | Permission is hereby granted, free of charge, to any person obtaining a copy 7 | of this software and associated documentation files (the "Software"), to deal 8 | in the Software without restriction, including without limitation the rights 9 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 | copies of the Software, and to permit persons to whom the Software is 11 | furnished to do so, subject to the following conditions: 12 | 13 | The above copyright notice and this permission notice shall be included in 14 | all copies or substantial portions of the Software. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 22 | THE SOFTWARE. -------------------------------------------------------------------------------- /tools/config-lister/LICENSE.txt: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) SpongePowered 4 | Copyright (c) contributors 5 | 6 | Permission is hereby granted, free of charge, to any person obtaining a copy 7 | of this software and associated documentation files (the "Software"), to deal 8 | in the Software without restriction, including without limitation the rights 9 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 | copies of the Software, and to permit persons to whom the Software is 11 | furnished to do so, subject to the following conditions: 12 | 13 | The above copyright notice and this permission notice shall be included in 14 | all copies or substantial portions of the Software. 15 | 16 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 17 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 18 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 19 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 20 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 21 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 22 | THE SOFTWARE. 23 | -------------------------------------------------------------------------------- /source/plugin/plugin-identifier.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | Plugin Identifiers 3 | ================== 4 | 5 | Sponge plugins are identified using a unique **plugin ID**, and a human-readable **plugin name**. It is important that 6 | you choose a proper name for your project now, because later plugins will interact with your plugin under your chosen 7 | plugin ID (e.g. when defining plugin dependencies). The plugin ID is also used for creating the default configuration 8 | folders for your plugin. 9 | 10 | .. note:: 11 | The plugin ID must be lowercase and start with an alphabetic character. It may only contain alphanumeric characters, 12 | dashes or underscores. The plugin name does **not** have such a limitation and can even contain spaces or 13 | special characters. It cannot be longer than 64 characters. 14 | 15 | Keep in mind your plugin ID will be the main identification of your plugin, used in other plugins as dependencies, for 16 | your configuration files, as well as other properties stored for your plugin. That's why it is important you always 17 | choose a proper plugin ID directly, because changing it again later will be difficult. 18 | 19 | Continue at :doc:`plugin-class` for an introduction how to set up your plugin class. 20 | -------------------------------------------------------------------------------- /source/about/license.rst: -------------------------------------------------------------------------------- 1 | ======= 2 | License 3 | ======= 4 | 5 | SpongeForge, SpongeVanilla, SpongeCommon, and the Sponge API are licensed under the MIT license. There is no contributor 6 | license agreement, and all contributions to the Sponge projects are welcome. We also explicitly grant permission to 7 | distribute SpongeForge in any third-party modpack. 8 | 9 | The MIT license is an extremely permissive license, placing almost no restrictions on what can be done with Sponge. 10 | The only requirement is that the copyright header must be left intact. 11 | 12 | There is true value in licensing Sponge under the MIT license, especially when considering the fate of other projects 13 | with goals similar to those of Sponge. The license offers peace-of-mind in ensuring Sponge has a bright future. Further 14 | details on the license can be found at https://choosealicense.com/licenses/mit/. 15 | 16 | The SpongeDocs are licensed differently under the 17 | `Creative Commons - Share-Alike license `_. 18 | 19 | Art assets are held under the 20 | `Creative Commons - Non Commercial, No Derivatives license `_. 21 | 22 | Contributions to the projects implicitly accept their respective licenses. 23 | -------------------------------------------------------------------------------- /tools/javadoc-checker/README.md: -------------------------------------------------------------------------------- 1 | Javadoc-Checker 2 | =============== 3 | 4 | A helper to search for invalid javadoc references. 5 | 6 | Requirements 7 | ------------ 8 | 9 | * Java 10 10 | * Maven 3.5 11 | 12 | Usage 13 | ----- 14 | 15 | This application takes two optional parameters: `[path_to_SpongeDocs/sources [checkDeprecated]]` 16 | 17 | There a three variants to run this project. 18 | 19 | ### Direct 20 | 21 | The simplest one is just run the following command in the command line: 22 | 23 | ````bash 24 | mvn 25 | ```` 26 | 27 | This uses the API version as specified in the pom and assumes it is executed from within the SpongeDocs repo. 28 | 29 | You can also pass command line arguments to this like: 30 | 31 | ````bash 32 | mvn -Dexec.args="../../source true" 33 | ```` 34 | 35 | ### Stand-alone 36 | 37 | Or you can build the jar and then run the stand-alone variant: 38 | 39 | ````bash 40 | mvn clean package 41 | java -jar javadoc-checker-x.y.z-API-a.b.c.jar 42 | ```` 43 | 44 | ### Independent 45 | 46 | Or use the independent version that can be used to check any API version: 47 | 48 | ````bash 49 | mvn clean package 50 | java -cp "spongeapi-a.b.c-shaded.jar;javadoc-checker-x.y.z-independent.jar" org.spongepowered.docs.tools.javadoc.Main 51 | ```` 52 | -------------------------------------------------------------------------------- /source/ore/routes/project-version.rst: -------------------------------------------------------------------------------- 1 | =================== 2 | Get Project Version 3 | =================== 4 | 5 | **GET /api/v1/projects/:pluginId/versions/:version** 6 | 7 | Returns a single project version for the project with the given plugin ID and the given version string. Note that there 8 | are no two versions in a project with the same version string. 9 | 10 | **Example output:** 11 | 12 | .. code-block:: json 13 | 14 | { 15 | "id": 1226, 16 | "createdAt": "2018-02-08 18:41:36.917", 17 | "name": "1.1", 18 | "dependencies": [{ 19 | "pluginId": "spongeapi", 20 | "version": "7.1.0" 21 | }], 22 | "pluginId": "auction", 23 | "channel": { 24 | "name": "Release", 25 | "color": "#009600" 26 | }, 27 | "fileSize": 11441, 28 | "md5": "d169809b0eda0e5d49bc60d5f69f097b", 29 | "staffApproved": false, 30 | "href": "/ewoutvs_/Auction/versions/1.1", 31 | "tags": [{ 32 | "id": 13, 33 | "name": "Sponge", 34 | "data": "7.1.0", 35 | "backgroundColor": "#F7Cf0D", 36 | "foregroundColor": "#000000" 37 | }], 38 | "downloads": 26, 39 | "author": "ewoutvs_" 40 | } 41 | -------------------------------------------------------------------------------- /source/server/spongineer/bugreport.rst: -------------------------------------------------------------------------------- 1 | Reporting Bugs 2 | ============== 3 | 4 | If you've encountered a bug and you're unsure on how to report it, this is the page to look at. 5 | We're currently handling all bug reports through our issue trackers on GitHub. 6 | 7 | If there is something wrong with the API or a feature missing you would like to see for developing 8 | plugins, please report it on the `SpongeAPI issue tracker `_. 9 | 10 | If there is something wrong with the server and you think the issue is Sponge related, 11 | report it on the `Sponge issue tracker `_. 12 | 13 | If you have an issue with the docs themselves, you can report it on the 14 | `SpongeDocs issue tracker `_. 15 | 16 | Before submitting an issue please make sure you have already read through our 17 | :doc:`debugging`, :doc:`troubleshooting` and :doc:`logs` sections. If the problem still persists, then file a bug 18 | report, utilizing the issue template provided by GitHub when you click the ``New Issue`` button and fill out everything 19 | applicable. If the project lacks an issue template, please make sure to include as much relevant information as 20 | possible. 21 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | #------- Build 2 | 3 | FROM crowdin/cli:latest as builder 4 | 5 | ARG GITHUB_USER 6 | ARG GITHUB_TOKEN 7 | ARG GITHUB_REPO 8 | ARG GITHUB_VERSION 9 | ARG CROWDIN_TOKEN 10 | ARG CROWDIN_PROJECT_ID 11 | ARG CROWDIN_BASE_URL 12 | ARG VERSION 13 | 14 | RUN apk add --no-cache python3 bash zip 15 | 16 | ENV VIRTUAL_ENV=/opt/venv 17 | RUN python3 -m venv $VIRTUAL_ENV 18 | ENV PATH="$VIRTUAL_ENV/bin:$PATH" 19 | 20 | WORKDIR /app 21 | 22 | COPY requirements.txt /app/requirements.txt 23 | 24 | RUN pip install -U -r requirements.txt 25 | 26 | COPY . /app 27 | 28 | RUN sphinx-build -W -d build/doctrees source build/html 29 | RUN sphinx-build -W -q -b gettext source build/locale 30 | 31 | RUN cd /app && crowdin download -b ${VERSION} 32 | 33 | RUN sphinx-intl build > /dev/null 34 | 35 | RUN export VERSIONS=`list-versions` \ 36 | && translations=`list-translations ${VERSION}` \ 37 | && for version in $VERSIONS ; do export LOCALES_$(echo $version | tr '.' '_')="en $(list-translations $version)" ; done \ 38 | && export LOCALES="en $translations" \ 39 | && build-language en \ 40 | && echo "$translations" | xargs -n1 -P4 build-language 41 | 42 | #------- Copy to nginx 43 | 44 | FROM nginx:1.29.0-alpine 45 | 46 | COPY --from=builder /app/dist /usr/share/nginx/html 47 | -------------------------------------------------------------------------------- /source/ore/index.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | Ore Documentation 3 | ================= 4 | 5 | Our custom built plugin hosting solution provides a unique and convenient way for content creators to share and 6 | make accessible plugins that they have created. For developers, Ore offers a centralized location where their users 7 | can download, review, and get support on their plugin. For server administrators, Ore offers a level of safety and 8 | security previously lacking from many Minecraft communities by offering two-factor authentication on user accounts, 9 | and having our staff carefully review each upload. 10 | 11 | Ore version 1.0 is now live, but development continues toward a 2.0 release. If you find an 12 | issue with Ore that you believe is a bug, please take the time to report it to our 13 | `issue tracker `__. 14 | 15 | If you need help using Ore, create a new topic on our 16 | `Ore Support Forum `__. 17 | 18 | If you'd like to submit a plugin to Ore, please read and follow the Ore plugin submission guidelines linked below. 19 | 20 | Contents 21 | ======== 22 | 23 | .. toctree:: 24 | :maxdepth: 2 25 | :titlesonly: 26 | 27 | guidelines 28 | publish 29 | security 30 | api 31 | 32 | -------------------------------------------------------------------------------- /source/preparing/jdk.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | Installing the JDK 3 | ================== 4 | 5 | The Java Development Kit - also known as the JDK - is required in order to develop Sponge plugins and/or work on Sponge 6 | itself. 7 | 8 | Download 9 | ======== 10 | 11 | Before installing the JDK, uninstall any older versions of Java that are present on your computer. 12 | 13 | .. note:: 14 | 15 | Sponge contributors and Plugin authors must use JDK 8, as older versions of Java are no longer supported. 16 | Be aware that some Minecraft servers have still not yet migrated to Java 8. To run Sponge and its plugins 17 | properly you must update to Java 8, as Sponge won't run on older versions (i.e. Java 6 and 7). 18 | 19 | Oracle provides free downloads of the Java Development Kit on their website. Ensure that you are installing the JDK 20 | (Java Development Kit), not the JRE (Java Runtime Environment). There is a difference between the two. 21 | 22 | * `Java Development Kit 8 `__ 23 | 24 | As an open source alternative you can also download the JDK from `AdoptOpenJDK `__. 25 | 26 | Upon completion of the installation process, reboot your computer. The JDK should then be ready for use. 27 | -------------------------------------------------------------------------------- /source/plugin/project/index.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | Setting Up Your Project 3 | ======================= 4 | 5 | Before you can start developing your Sponge plugin, you need to set up the SpongeAPI dependency in your project. If 6 | you're already experienced with your build system, below is the Maven dependency you need to add. Otherwise, there is a 7 | more detailed explanation at the :doc:`Gradle ` and :doc:`Maven ` page. 8 | 9 | SpongeAPI dependency 10 | ==================== 11 | 12 | Maven repository 13 | ~~~~~~~~~~~~~~~~ 14 | 15 | ==== ======================================= 16 | Name ``sponge`` 17 | URL ``https://repo.spongepowered.org/repository/maven-public/`` 18 | ==== ======================================= 19 | 20 | Maven dependency 21 | ~~~~~~~~~~~~~~~~ 22 | 23 | ============= ============================================================================ 24 | Group ID ``org.spongepowered`` 25 | Artifact ID ``spongeapi`` 26 | Version For example: ``8.0.0`` (stable), or ``8.1.0-SNAPSHOT`` (dev build, unstable) 27 | ============= ============================================================================ 28 | 29 | Setting Up Your Project 30 | ======================= 31 | 32 | .. toctree:: 33 | :maxdepth: 2 34 | :titlesonly: 35 | 36 | gradle 37 | maven 38 | version-numbers 39 | -------------------------------------------------------------------------------- /source/contributing/implementation/debugging/more.rst: -------------------------------------------------------------------------------- 1 | ================ 2 | More Information 3 | ================ 4 | 5 | .. note:: 6 | 7 | This page is not complete. If you feel like you can help, you can do so on `our GitHub repository 8 | `_. Also see the `related GitHub Issue 9 | `_ for more information on what is required. 10 | 11 | Sponge 12 | ------ 13 | 14 | The following sections in the SpongeDocs can provide more information for debugging: 15 | 16 | - :doc:`/server/getting-started/configuration/index` 17 | - :doc:`/server/spongineer/index` 18 | - :doc:`/about/structure` 19 | 20 | There also are links at the bottom of the SpongeDocs' home page which leads you to other resources for help and 21 | information. 22 | 23 | Mixin 24 | ----- 25 | 26 | Learn about `Mixin `_ on its `wiki 27 | `_ and `javadoc `_ 28 | sites. 29 | 30 | IntelliJ 31 | -------- 32 | 33 | Learn about `Git Integration `_ and `Project 34 | Structure `_ on JetBrains' 35 | web site. 36 | -------------------------------------------------------------------------------- /source/server/management/permissions.rst: -------------------------------------------------------------------------------- 1 | ==================== 2 | Managing Permissions 3 | ==================== 4 | 5 | You can configure who has access to what if you are running a server by making use of :doc:`/plugin/permissions`. 6 | Specific permissions for Sponge, Forge and Minecraft commands are shown on the :doc:`../spongineer/commands` page. 7 | 8 | 9 | Operator Level 10 | ============== 11 | 12 | Minecraft comes with a simple way to give permissions: by setting users as operator (or "op" for short). General 13 | information on op status can be found at https://minecraft.wiki/w/Server#Managing_and_maintaining_a_server 14 | 15 | The abilities of op permission may be adjusted by altering the ``op-permission-level`` setting in the 16 | `server.properties `__ file. 17 | 18 | A list of native Minecraft server commands available to players with op can be found at the `Minecraft Wiki 19 | `_. 20 | 21 | 22 | .. warning:: 23 | Minecraft does not have any fine-grained permissions capacity, only op. This is a very high level of permission and 24 | should be reserved for trusted players. More complicated permission setups require the use of a permissions plugin 25 | or mod. Sponge is not a permissions-management plugin. 26 | 27 | 28 | .. note:: 29 | Some plugins and mods may also grant specific permissions to ops. 30 | -------------------------------------------------------------------------------- /source/plugin/event/index.rst: -------------------------------------------------------------------------------- 1 | ====== 2 | Events 3 | ====== 4 | 5 | .. javadoc-import:: 6 | org.spongepowered.api.event.Cancellable 7 | 8 | Events are used to inform plugins of certain happenings. Many events can also be *cancelled* -- that is, the action that 9 | the event refers to can be prevented from occurring. Cancellable events implement the :javadoc:`Cancellable` interface. 10 | 11 | Sponge itself contains many events; however, plugins can create their own events which other plugins can listen to. 12 | 13 | Event listeners are assigned a priority that determines the order in which the event listener is run in context of other 14 | event listeners (such as those from other plugins). For example, an event listener with ``EARLY`` priority will return 15 | before most other event listeners. See :ref:`about_listener` for more information. 16 | 17 | Events cannot be sent to a specific set of plugins. All plugins that listen to an event will be notified of the event. 18 | 19 | The event bus or event manager is the class that keeps track of which plugins are listening to which event, 20 | and is also responsible for distributing events to event listeners. 21 | 22 | Sponge provides a built-in callback for plugin reloading. See the :ref:`game-reload` section for more information. 23 | 24 | 25 | Contents 26 | ======== 27 | 28 | .. toctree:: 29 | :maxdepth: 2 30 | :titlesonly: 31 | 32 | listeners 33 | causes 34 | filters 35 | custom 36 | -------------------------------------------------------------------------------- /source/server/getting-started/configuration/sponge-conf.rst: -------------------------------------------------------------------------------- 1 | =========== 2 | global.conf 3 | =========== 4 | 5 | Global Configuration 6 | ~~~~~~~~~~~~~~~~~~~~ 7 | 8 | The global.conf file contains the global configuration settings for Sponge. This file is created in the config/sponge 9 | directory in your server folder. Many of these properties can be also overridden per-world or per-dimension type by 10 | using the config files in the subfolders of config/worlds. 11 | 12 | Below is a list of available config settings and their comments inside the global.conf file. Note that certain sections 13 | will not be filled immediately, and may optionally be added to the file when the server encounters them. There's also 14 | full example of an unmodified ``global.conf`` file at the bottom of this page, below the following list: 15 | 16 | .. note:: 17 | 18 | The following section headings refer to the path within the configuration (and the corresponding simple class name). 19 | Each of the entries in a section refers to a configurable property in the associated class. The `Type` information 20 | refers to the section/class that describes the nested configuration structure. 21 | 22 | .. include:: global.conf-rst.generated 23 | 24 | ------------------------------------------------------------------------------------------------------------ 25 | 26 | This configuration file was generated using SpongeForge 7.3.0 (Forge 2838, SpongeAPI 7.3): 27 | 28 | .. literalinclude:: global.conf 29 | :language: guess 30 | -------------------------------------------------------------------------------- /source/ore/security.rst: -------------------------------------------------------------------------------- 1 | ======== 2 | Security 3 | ======== 4 | 5 | Spongie takes security very seriously. For this reason, all uploaded plugins are PGP signed to ensure you’re getting 6 | what the plugin author intended to upload and are immediately queued to go through a meticulous vetting process. 7 | 8 | .. note:: 9 | 10 | Ore will warn you if you attempt to download a plugin that has not been cleared by our reviewing process. 11 | We disclaim all responsibility for any harm to your server or system should you choose not to heed the warning. 12 | 13 | Ore requires all plugin submissions to be signed with 14 | `Pretty Good Privacy (PGP) `_ for security purposes. This helps us 15 | verify that the identity of the uploader is indeed the same identity of the account holder. This means that if your 16 | account were to become compromised, the attacker would need your private key to upload plugins to Ore. This alone 17 | dramatically reduces the chances of having malicious code uploaded to and associated with your account. 18 | 19 | You can read about how to *upload a public key to your account* and how to *sign your plugins with your private key* 20 | :doc:`/ore/publish`. 21 | 22 | Additionally, while not required, we highly recommend you enable two-factor authentication on your account to prevent it 23 | from being compromised. You can enable two-factor authentication in your general Sponge account settings 24 | `here `_. 25 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Sponge Documentation ![Build Status](https://github.com/spongepowered/spongedocs/actions/workflows/build.yml/badge.svg) 2 | 3 | This is the repository where the Sponge documentation is held. 4 | 5 | 6 | The latest version may be viewed in full by visiting [Sponge Docs](https://docs.spongepowered.org/) 7 | 8 | ## Contributing 9 | 10 | Instructions and Guidelines on how to contribute can be found on [the Docs themselves](https://docs.spongepowered.org/stable/en/contributing/spongedocs.html). 11 | 12 | ## Licensing 13 | 14 | The Sponge Documentation is licensed under the [Creative Commons - Share-Alike license](LICENSE.txt). 15 | 16 | You can read more about our licensing situation on the [documentation itself](https://docs.spongepowered.org/stable/en/about/license.html). 17 | 18 | ## Translations 19 | 20 | We're eagerly looking for translators! Please visit the [Crowdin translation page](https://translate.spongepowered.org), sign up, join the team, and start translating. 21 | 22 | ## Local Environment 23 | 24 | You can setup an environment so you can instantly see the changes that have been made to the docs. 25 | 26 | 1. [Install Python 3](https://www.python.org) 27 | 2. [Install node.js](https://nodejs.org) 28 | 29 | In terminal or the command line, within the directory containing this README, run the following commands: 30 | 31 | npm install -g gulp 32 | npm install 33 | pip install -r requirements.txt 34 | gulp 35 | 36 | Your browser should open to reveal the docs. When you make a change to the documentation, the docs should refresh in the browser (possibly after a few seconds). 37 | -------------------------------------------------------------------------------- /gulpfile.js: -------------------------------------------------------------------------------- 1 | import { deleteAsync } from 'del' 2 | import gulp from 'gulp' 3 | import pluginerror from 'plugin-error' 4 | import browsersync from 'browser-sync' 5 | import {spawn} from 'child_process' 6 | 7 | const devServer = browsersync.create(); 8 | 9 | function shell(plugin, command, args) { 10 | return (done) => 11 | spawn(command, args, {stdio: 'inherit'}) 12 | .on('error', (err) => { 13 | done(new pluginerror(plugin, err)) 14 | }) 15 | .on('exit', (code) => { 16 | if (code == 0) { 17 | // Process completed successfully 18 | done() 19 | } else { 20 | done(new pluginerror(plugin, `Process failed with exit code ${code}`)); 21 | } 22 | }) 23 | } 24 | 25 | function webserver(done) { 26 | devServer.init({ 27 | watch: true, 28 | server: "./build/dev/html/" 29 | }, function () { this.server.on('close', done) }) 30 | }; 31 | 32 | 33 | function watch() { 34 | gulp.watch('./source/**', gulp.series('sphinx:dev')); 35 | }; 36 | 37 | gulp.task('clean', () => deleteAsync(['build'])); 38 | 39 | gulp.task('sphinx', shell( 40 | 'sphinx', 'sphinx-build', ['-W', '-d', 'build/doctrees', 'source', 'build/html'] 41 | )); 42 | 43 | gulp.task('sphinx:dev', shell( 44 | 'sphinx', 'sphinx-build', ['source', 'build/dev/html'] 45 | )); 46 | 47 | gulp.task('build', gulp.series('clean', 'sphinx')); 48 | gulp.task('build:dev', gulp.series('clean', 'sphinx:dev')); 49 | 50 | gulp.task('default', gulp.series('build:dev', gulp.parallel(webserver, watch))); 51 | -------------------------------------------------------------------------------- /source/contributing/implementation/debugging/index.rst: -------------------------------------------------------------------------------- 1 | ================ 2 | Debugging Sponge 3 | ================ 4 | 5 | .. tip:: 6 | See :doc:`/plugin/debugging` for debugging a plugin and :ref:`usingDebugger` tips. 7 | 8 | These sections provide information for debugging Sponge itself. Whether you need to debug SpongeForge, SpongeVanilla, 9 | SpongeCommon, or SpongeAPI, set up your workspace for a SpongeForge or SpongeVanilla implementation. SpongeCommon and 10 | SpongeAPI are debugged within the implementation setup. 11 | 12 | See :doc:`/about/structure` for more information. 13 | 14 | .. note:: 15 | Be sure to read and understand :doc:`/contributing/howtogit` and :doc:`/contributing/versioning` as well as the 16 | entirety of the :doc:`../index` sections before proceeding. 17 | 18 | .. _setupWorkspace: 19 | 20 | Setup the Workspace 21 | =================== 22 | 23 | Here are the steps to setup your workspace if you do not have one already: 24 | 25 | 1. Clone the implementation. 26 | 2. Make changes to the local repository (e.g. create new branch if you will make changes). 27 | 3. Setup the implementation. 28 | 4. Build the implementation. 29 | 5. Run the implementation. 30 | 31 | With these instructions successfully completed, you are ready to import the project into your IDE. 32 | 33 | .. note:: 34 | This is an outline of the steps necessary to setup the workspace. See the `Sponge 35 | `_ GitHub page for complete instructions on cloning, setup, building, 36 | and running the implementations. 37 | 38 | Contents 39 | ======== 40 | 41 | .. toctree:: 42 | :maxdepth: 2 43 | :titlesonly: 44 | 45 | git 46 | ide 47 | testing 48 | issues 49 | mixin 50 | tools 51 | more 52 | faq 53 | -------------------------------------------------------------------------------- /source/server/getting-started/implementations/spongevanilla.rst: -------------------------------------------------------------------------------- 1 | ======================== 2 | Installing SpongeVanilla 3 | ======================== 4 | 5 | SpongeVanilla is a vanilla implementation of SpongeAPI as a stand-alone server. 6 | 7 | 8 | Overview 9 | ======== 10 | 11 | SpongeVanilla is an implementation of SpongeAPI that is created by patching the vanilla Minecraft server. This 12 | means it is a stand-alone server, and does not utilize nor require Minecraft Forge or Forge mod loader (FML). 13 | SpongeVanilla is being developed in parallel to the Forge version of Sponge, as an alternative platform for users who 14 | do not want to run a Forge server. Originally started as an independent project and named Granite, by developers 15 | **AzureusNation** and **VoltaSalt**, the SpongeVanilla team officially joined the Sponge development team in March 2015. 16 | 17 | Download 18 | ======== 19 | 20 | Review our :doc:`/versions/versioning` and grab your copy of `SpongeVanilla here 21 | `_. 22 | 23 | Installing SpongeVanilla 24 | ======================== 25 | 26 | .. note:: 27 | 28 | If you use (or are planning to use) a game server host, they may have a control panel that can install Sponge for 29 | you. 30 | 31 | 32 | SpongeVanilla only works as a dedicated server. 33 | 34 | 1. Download the SpongeVanilla .jar from the Sponge website. 35 | #. Run it via command line: ``java -jar spongevanilla-whatever.jar`` 36 | #. Set up :doc:`../port-forward` to ensure others can connect. 37 | 38 | .. warning:: 39 | 40 | Don't double-click the ``.jar`` file, as it will start the server without a window to control it! 41 | 42 | 43 | Links 44 | ===== 45 | 46 | * `Homepage `__ 47 | * `GitHub `__ 48 | -------------------------------------------------------------------------------- /source/server/getting-started/jre.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Installing Java 3 | =============== 4 | 5 | Java is needed to run Sponge and Minecraft: Java Edition. You most likely already have Java, but you may need to update 6 | it. 7 | 8 | SpongeAPI 7 and 8 requires Java 8 (specifically ``1.8.0_20`` or above). SpongeAPI 8 will also run on later versions of 9 | Java, we recommend Java 17 as the latest LTS version. 10 | 11 | Installing Java 12 | =============== 13 | 14 | If you have Windows or macOS for your computer, you can `download builds of OpenJDK from Adoptium here 15 | `__. Builds of Java 8, 11 and 17 are all available here. 16 | 17 | You may have to configure the path to the JRE/JDK in your 18 | 19 | * launcher using ``Profile`` (``Advanced Options``) -> ```` -> ``Java-Executable`` (``.../java.exe``) 20 | * server using either the ``PATH`` variable or using the full path to your java executable 21 | 22 | 32-bit vs. 64-bit 23 | ~~~~~~~~~~~~~~~~~ 24 | 25 | If your computer supports it, you should use 64-bit versions of Java whenever possible. Most modern computers will be 26 | running 64-bit operating systems. The Adoptium site linked above should detect what you're running and offer the correct 27 | download. 28 | 29 | It is also possible to look this up in the system information window. 30 | 31 | * Windows: Press ```` + ```` or via ``Systeminformation`` have a look at your ``system type``. 32 | * Linux: Open a terminal and type ``arch`` or ``uname -m``. ``i686`` -> 32-bit. ``x86_64`` -> 64-bit. 33 | * macOS: All supported Macs are 64-bit - however if you are running an Apple Silicon machine, choose arm64 over x64. 34 | 35 | If you are sure to about your system's architecture you can 36 | `manually choose `__ the correct installer yourself. 37 | -------------------------------------------------------------------------------- /source/about/posting.rst: -------------------------------------------------------------------------------- 1 | ======================== 2 | Forum Posting Guidelines 3 | ======================== 4 | 5 | 6 | Read Before Posting 7 | ------------------- 8 | 9 | If you are confused or curious about Sponge, we strongly recommend reading the :doc:`faq`. 10 | 11 | Please refrain from posting topics asking for basic information about Sponge, like *"Is Sponge a Forge mod"*, *"When 12 | will Sponge be released"*, etc. Answers to those questions can be found here in SpongeDocs. 13 | 14 | Before you post a new topic on Sponge Forums, please make sure it's not redundant questions or information! Use the 15 | Search feature (top right of page) or check the ``Your topic is similar to...`` box that appears above the pane when 16 | creating a new topic (it updates as you add stuff to your topic). If there is a similar topic, you should probably 17 | continue your discussion there! 18 | 19 | Discussions about other APIs are allowed so long as they don't turn nasty. 20 | 21 | Still need more info? Take a look at the Sponge resources in the :doc:`/index`, check the `Forum Announcements 22 | `__, or to track Sponge's progress, `follow them on Twitter 23 | `__ or watch `Sponge GitHub `__. If you are really 24 | keen to help development, look at :doc:`/contributing/index`. 25 | 26 | 27 | Forum Rules 28 | ----------- 29 | 30 | - A complete list of rules and guidelines for Sponge Forums can be found in :doc:`rules`. 31 | 32 | 33 | Categorizing Your Posts 34 | ----------------------- 35 | 36 | When creating new topics, use the drop-down menu to the right of the topic title to set its category. Try to make sure 37 | this category fits what you're posting about. If you don't know what a category implies, a description is next to each 38 | one in the drop down. 39 | 40 | 41 | **Thanks for reading & welcome to the Sponge community!** 42 | -------------------------------------------------------------------------------- /source/plugin/internals/index.rst: -------------------------------------------------------------------------------- 1 | ================================ 2 | Implementation-dependent Plugins 3 | ================================ 4 | 5 | .. warning:: 6 | These docs were written for SpongeAPI 7 and are likely out of date. 7 | `If you feel like you can help update them, please submit a PR! `__ 8 | 9 | There are various reasons for bypassing SpongeAPI and accessing the internal Minecraft implementation directly: 10 | 11 | - A part of SpongeAPI is not implemented yet. In this case you can temporarily bypass the API in your plugins. However, 12 | in most cases the better option is attempting to contribute the missing implementation to Sponge so other plugin 13 | developers can profit from the implemented API. 14 | - You need access to an implementation-dependent feature which is not supported by SpongeAPI (on purpose). 15 | - You want to optimize or customize the implementation specifically for your server. 16 | 17 | .. warning:: 18 | Depending on special implementation features will make your plugin only work on the implementation you build it 19 | against (and likely also only on a specific version). Unless you are certain that accessing the implementation is 20 | necessary we highly recommend building plugins only against SpongeAPI. 21 | 22 | .. note:: 23 | The following articles assume you build your plugin for SpongeVanilla/SpongeForge. The plugin will not be usable on 24 | any other implementation. 25 | 26 | SpongeVanilla and SpongeForge use MCP as development environment for the internal Minecraft code. Continue at :doc:`mcp` 27 | for a short overview about MCP or continue directly with :doc:`mcp-setup` for an introduction about using MCP in 28 | plugins. 29 | 30 | Contents 31 | ======== 32 | 33 | .. toctree:: 34 | :maxdepth: 2 35 | :titlesonly: 36 | 37 | mcp 38 | mcp-setup 39 | access-transformers 40 | mixins 41 | implementation 42 | -------------------------------------------------------------------------------- /source/contributing/implementation/git-implementation.rst: -------------------------------------------------------------------------------- 1 | ======================================== 2 | Git Workflow for API and Implementations 3 | ======================================== 4 | 5 | Developing the API 6 | ================== 7 | 8 | The basic process of adding your changes is explained in the :doc:`../howtogit` section. On top of that we suggest that 9 | you create your new branch with a meaningful name. With the new branching model, you need to be aware which 10 | branch you need to base your PRs on and where it should get merged afterwards. Read about the new branching and 11 | versioning model here: :doc:`../versioning` 12 | 13 | Additionally, we require that you ensure the module will compile with ``gradle compileJava``. 14 | This will run a simple build of the source files. When finished successfully, you can PR your changes to SpongeAPI 15 | repo. 16 | 17 | Developing the Implementation 18 | ============================= 19 | 20 | The process for the implementations is almost the same as for the API. You add your changes as described in 21 | :doc:`../howtogit`. Note that you should give your branches a meaningful name. With the new branching model, you need to 22 | be aware which branch you need to base your PRs on and where it should get merged afterwards. Read about the new 23 | branching and versioning model here: :doc:`../versioning` 24 | 25 | Run ``gradle compileJava`` to check if everything compiles without errors. 26 | 27 | Since you are working on the implementation, there is a possibility that your work included changes in the API. This is 28 | okay. Just remember to ensure the pointers for the version of SpongeAPI match the version of your branch prior to 29 | committing and pushing. To do this, you may need to add the submodules to the commit (with ``git add SpongeAPI`` and/or 30 | ``git add Mixin``) prior to committing on your implementation work. 31 | 32 | You may open a pull request once your commit is pushed to your fork or the repository. 33 | -------------------------------------------------------------------------------- /source/server/management/whitelist.rst: -------------------------------------------------------------------------------- 1 | ====================== 2 | Managing the Whitelist 3 | ====================== 4 | 5 | The whitelist allows you to control who can join your server. Be aware that ops will *always* be able to connect to the 6 | server, regardless of whether they're in the whitelist. 7 | 8 | When the whitelist function is enabled, only players named on the whitelist will be allowed to login to your server. 9 | Players can be added to the whitelist through the usage of in-game :doc:`../spongineer/commands` or by editing the 10 | ``whitelist.json`` file. 11 | 12 | - To enable the whitelist, use ``/whitelist on`` 13 | - To disable the whitelist, use ``/whitelist off`` 14 | - To add a player to the whitelist, use ``/whitelist add playername`` 15 | - To remove a player from the whitelist, use ``/whitelist remove playername`` 16 | - To show all players on the whitelist, use ``/whitelist list`` 17 | - To reload the whitelist after a manual change to the file, use ``/whitelist reload`` 18 | 19 | The whitelist can also be enabled or disabled by editing the 20 | `server.properties `__ file, 21 | although this will only affect the game after server reload or restart. 22 | 23 | Permissions 24 | =========== 25 | 26 | You can also use these :doc:`/plugin/permissions` to manage the access to your server. 27 | 28 | =================================== ==================================================================== 29 | Permission Description 30 | =================================== ==================================================================== 31 | minecraft.login.bypass-whitelist Treat the user as whitelisted. Defaults to ``Op``-only. 32 | minecraft.login.bypass-player-limit Allow this user to bypass the server's player limit. Defaults to the 33 | ``bypassesPlayerLimit`` option in ``ops.json``. 34 | =================================== ==================================================================== 35 | -------------------------------------------------------------------------------- /source/ore/routes/project.rst: -------------------------------------------------------------------------------- 1 | =========== 2 | Get Project 3 | =========== 4 | 5 | **GET /api/v1/projects/:pluginId** 6 | 7 | Returns a single project with a given plugin ID. Note that there are no two plugins on Ore with the same plugin ID. 8 | 9 | **Sample output:** 10 | 11 | .. code-block:: json 12 | 13 | { 14 | "pluginId": "auction", 15 | "createdAt": "2018-01-23 11:08:55.456", 16 | "name": "Auction", 17 | "owner": "ewoutvs_", 18 | "description": "Auction for players", 19 | "href": "/ewoutvs_/Auction", 20 | "members": [{ 21 | "userId": 21366, 22 | "name": "ewoutvs_", 23 | "roles": ["Owner"], 24 | "headRole": "Owner" 25 | }], 26 | "channels": [{ 27 | "name": "Release", 28 | "color": "#009600" 29 | }], 30 | "recommended": { 31 | "id": 1226, 32 | "createdAt": "2018-02-08 18:41:36.917", 33 | "name": "1.1", 34 | "dependencies": [{ 35 | "pluginId": "spongeapi", 36 | "version": "7.1.0" 37 | }], 38 | "pluginId": "auction", 39 | "channel": { 40 | "name": "Release", 41 | "color": "#009600" 42 | }, 43 | "fileSize": 11441, 44 | "md5": "d169809b0eda0e5d49bc60d5f69f097b", 45 | "staffApproved": false, 46 | "href": "/ewoutvs_/Auction/versions/1.1", 47 | "tags": [{ 48 | "id": 13, 49 | "name": "Sponge", 50 | "data": "7.1.0", 51 | "backgroundColor": "#F7Cf0D", 52 | "foregroundColor": "#000000" 53 | }], 54 | "downloads": 26, 55 | "author": "ewoutvs_" 56 | }, 57 | "category": { 58 | "title": "Gameplay", 59 | "icon": "fa-puzzle-piece" 60 | }, 61 | "views": 287, 62 | "downloads": 53, 63 | "stars": 4 64 | } 65 | -------------------------------------------------------------------------------- /source/plugin/economy/implementing.rst: -------------------------------------------------------------------------------- 1 | ============================ 2 | Implementing the Economy API 3 | ============================ 4 | 5 | .. javadoc-import:: 6 | org.spongepowered.api.event.economy.EconomyTransactionEvent 7 | org.spongepowered.api.service.economy.Currency 8 | org.spongepowered.api.service.economy.EconomyService 9 | org.spongepowered.api.service.economy.account.UniqueAccount 10 | org.spongepowered.api.service.economy.account.VirtualAccount 11 | org.spongepowered.api.service.economy.transaction.TransactionResult 12 | org.spongepowered.api.service.economy.transaction.TransferResult 13 | 14 | Sponge provides interfaces for economy plugins to implement and create an API. In order to build a complete Economy 15 | API, you must implement six classes: 16 | 17 | * :javadoc:`Currency` 18 | * :javadoc:`EconomyService` 19 | * :javadoc:`TransactionResult` 20 | * :javadoc:`TransferResult` 21 | * :javadoc:`UniqueAccount` 22 | * :javadoc:`VirtualAccount` 23 | * :javadoc:`EconomyTransactionEvent` 24 | 25 | Registering Your Economy Service 26 | ================================ 27 | 28 | When it comes to registering any service in Sponge, you can provide your service as an option with Sponge deciding 29 | which service to use if requested. This means that if two Economy Service plugins are used on a server, only one 30 | of the services will be used. 31 | 32 | .. code-block:: java 33 | 34 | @Listener 35 | public void registerEconomyService(ProvideServiceEvent.EngineScoped event){ 36 | event.suggest(() -> new MyCustomEconomyService()); 37 | } 38 | 39 | Things to consider when implementing the Economy API 40 | ==================================================== 41 | 42 | * Do I want to include support for multiple currency types? 43 | * Do I want to my plugin to perform different actions when given different contexts? 44 | 45 | Implementing the Economy API is fairly straightforward, and the `JavaDocs `_ can be a 46 | great tool if you are unsure what a method is supposed to do. 47 | -------------------------------------------------------------------------------- /tools/code-checker/src/test/java/org/spongepowered/docs/tools/codeblock/KeywordBasedDeIndenterTest.java: -------------------------------------------------------------------------------- 1 | /* 2 | * This file is part of SpongeAPI, licensed under the MIT License (MIT). 3 | * 4 | * Copyright (c) SpongePowered 5 | * Copyright (c) contributors 6 | * 7 | * Permission is hereby granted, free of charge, to any person obtaining a copy 8 | * of this software and associated documentation files (the "Software"), to deal 9 | * in the Software without restriction, including without limitation the rights 10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 | * copies of the Software, and to permit persons to whom the Software is 12 | * furnished to do so, subject to the following conditions: 13 | * 14 | * The above copyright notice and this permission notice shall be included in 15 | * all copies or substantial portions of the Software. 16 | * 17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 | * THE SOFTWARE. 24 | */ 25 | package org.spongepowered.docs.tools.codeblock; 26 | 27 | import static org.junit.jupiter.api.Assertions.assertEquals; 28 | 29 | import java.util.Arrays; 30 | import java.util.stream.Collectors; 31 | import java.util.stream.Stream; 32 | 33 | import org.junit.jupiter.api.Test; 34 | 35 | class KeywordBasedDeIndenterTest { 36 | 37 | @Test 38 | void test() { 39 | assertEquals(Arrays.asList("Hello", "World", " PARTY", "ON", "FIRE", "", "", "ON", " NOPE"), 40 | Stream.of("Hello", "World", " PARTY", " ON", " FIRE", "", " ", "ON", " NOPE") 41 | .map(new KeywordBasedDeIndenter(s -> s.trim().equals("ON"))) 42 | .collect(Collectors.toList())); 43 | } 44 | 45 | } 46 | -------------------------------------------------------------------------------- /source/plugin/offline-userplayer-data.rst: -------------------------------------------------------------------------------- 1 | =================== 2 | Offline Player Data 3 | =================== 4 | 5 | .. javadoc-import:: 6 | org.spongepowered.api.entity.living.player.server.ServerPlayer 7 | org.spongepowered.api.entity.living.player.User 8 | org.spongepowered.api.profile.GameProfileManager 9 | org.spongepowered.api.user.UserManager 10 | 11 | It may be necessary for plugins to access player data even when the player is offline. 12 | You might think that ``Sponge.server().player()`` returning a :javadoc:`ServerPlayer` can be used for this. 13 | But since all ``Player`` objects only exist for online players, 14 | another solution must be used. 15 | 16 | Some plugins store the relevant data themselves and associate the user by using the :javadoc:`GameProfileManager`. 17 | But writing different code for offline and online users is not necessary. 18 | The :javadoc:`UserManager` is capable of returning :javadoc:`User` instances for ``Player``\s who are currently 19 | offline. 20 | 21 | Code Example 22 | ------------ 23 | 24 | Here's an example for a utility method that can be used to get a ``User``: 25 | 26 | .. code-block:: java 27 | 28 | import java.util.Optional; 29 | import java.util.UUID; 30 | import java.util.concurrent; 31 | 32 | import org.spongepowered.api.Sponge; 33 | import org.spongepowered.api.entity.living.player.User; 34 | import org.spongepowered.api.user.UserManager; 35 | 36 | public CompletableFuture> getUser(UUID uuid) { 37 | UserManager userManager = Sponge.server().userManager(); 38 | return userManager.load(uuid); 39 | } 40 | 41 | This code will get the ``UserManager`` and then retrieve the ``User`` from there. 42 | 43 | .. note:: 44 | 45 | The ``UserManager`` will use local cached versions of the user, however will contact Mojang servers if 46 | the user has not previously joined, hence why the load returns a ``CompletableFuture``. If the user 47 | cannot be found in either cache or Mojang then the ``CompletableFuture`` will return ``Optional.empty`` 48 | 49 | .. note:: 50 | 51 | You can check if the player is loaded in cache with the ``exists(UUID playerUuid)`` method found in 52 | ``UserManager`` 53 | -------------------------------------------------------------------------------- /source/plugin/inventory/events.rst: -------------------------------------------------------------------------------- 1 | .. _inventory-events: 2 | 3 | ================ 4 | Inventory Events 5 | ================ 6 | 7 | Inventory events have a bunch of sub-events for specific actions that happen but they usually fall in those 3 base categories: 8 | 9 | Events changing an inventory: `ChangeInventoryEvent`. 10 | Events for interactions with a container (open inventory): `InteractContainerEvent`/`ClickContainerEvent`. 11 | Events for hopper or droppers transferring items: `TransferInventoryEvent` 12 | 13 | All `InteractContainerEvent` have a cursor transaction which represent the change of the stack the player is holding on its cursor. 14 | All `ChangeInventoryEvent` have a list of slot-transactions which represent the changes on slots in the inventory. 15 | `ClickContainerEvent` may have a primary interaction slot. 16 | 17 | Some examples: 18 | Picking up an item with left-click in an inventory will cause a change on the cursor and one slot-transaction on the clicked slot. Event `ClickContainerEvent.Primary` 19 | Transferring an item to the other inventory with shift-left-click in an inventory will cause no change on the cursor and but two slot-transaction on the clicked slot and target slot. Event `ClickContainerEvent.Shift.Primary` 20 | Dropping a single item from the cursor with right-click outside the menu will cause a change on the cursor. Event: `ClickContainerEvent.Drop.Outside.Secondary` 21 | Filling in a recipe using the recipe-book will cause a bunch of slot-transactions. Event: `ClickContainerEvent.Recipe.Single` 22 | Scrolling through the hotbar has no cursor or slot-transactions. Event: ChangeInventoryEvent.Held 23 | 24 | Crafting Events 25 | =============== 26 | 27 | Crafting events fire in addition to the normal click events to allow plugins to change or cancel the recipe result. 28 | 29 | `CraftItemEvent.Preview` fires after completing a recipe. Canceling it removes the result from the crafting output slot. 30 | `CraftItemEvent.Craft` fires taking an item out of the crafting slot in any way. 31 | 32 | Enchanting Events 33 | ================= 34 | 35 | Enchanting an item happens in three steps: 36 | `EnchantItemEvent.CalculateLevelRequirement` 37 | `EnchantItemEvent.CalculateEnchantment` 38 | `EnchantItemEvent.Post` 39 | 40 | 41 | 42 | 43 | 44 | -------------------------------------------------------------------------------- /source/server/getting-started/configuration/hocon.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | Introduction to HOCON 3 | ===================== 4 | 5 | HOCON (Human-Optimized Config Object Notation) is an easy-to-use configuration format. It is used by Sponge and 6 | individual plugins utilizing SpongeAPI to store important data, such as configuration or player data. HOCON files 7 | typically use the suffix ``.conf``. 8 | 9 | Components 10 | ========== 11 | 12 | * a ``key`` is a string preceding a value 13 | * a ``value`` is a string, number, object, array, or boolean following a ``key`` 14 | * a ``key-value separator`` separates keys from values, and can be either ``:`` or ``=`` 15 | * a ``comment`` is prefixed with ``#`` or ``//``, typically serving to provide feedback or instructions 16 | 17 | **Example:** 18 | 19 | .. code-block:: guess 20 | 21 | yellow-thing: "Sponge" 22 | 23 | In this example, the ``key`` is ``yellow-thing``, the ``value`` is ``Sponge``, and the ``key-value separator`` is ``:``. 24 | 25 | Working with HOCON 26 | ================== 27 | 28 | HOCON is more flexible than the JSON (JavaScript Object Notation) format in that there are several ways to write valid 29 | HOCON. Below are two examples of valid HOCON. 30 | 31 | **Example #1:** 32 | 33 | .. code-block:: text 34 | 35 | player: { 36 | name: "Steve", 37 | level: 30 38 | } 39 | 40 | **Example #2:** 41 | 42 | .. code-block:: text 43 | 44 | player { 45 | name = "Steve" 46 | level = 30 47 | } 48 | 49 | In practice, it is best to follow the formatting conventions of the HOCON configuration you are editing. When editing 50 | a HOCON configuration for Sponge or an individual plugin utilizing SpongeAPI, the values are likely the only thing 51 | you will be changing unless otherwise specified. 52 | 53 | Debugging your configuration 54 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 55 | 56 | If a HOCON configuration does not appear to be working, here are some tips. 57 | 58 | * Curly braces must be balanced 59 | * Quotation marks must be balanced 60 | * Duplicate keys that appear later take precedence 61 | 62 | Specification 63 | ============= 64 | 65 | More information about the HOCON format can be found `here `__. 66 | -------------------------------------------------------------------------------- /source/server/getting-started/implementations/index.rst: -------------------------------------------------------------------------------- 1 | ========================== 2 | Choosing an Implementation 3 | ========================== 4 | 5 | Something that runs Sponge plugins is called an *implementation*. As long as a plugin is correctly made using the 6 | SpongeAPI, it should run correctly on any sufficiently-complete implementation. 7 | 8 | Minecraft can't run Sponge plugins out of the box, but you can modify it to do so. 9 | 10 | SpongeAPI itself is an `open standard `__. 11 | 12 | Available Implementations 13 | ========================= 14 | 15 | There are currently two implementations: 16 | 17 | +--------------------------------------+----------------------------------------------------------------+ 18 | | Name | Based on | 19 | +======================================+================================================================+ 20 | | :doc:`SpongeForge ` | Mojang's "vanilla" Minecraft: Java Edition and Minecraft Forge | 21 | +--------------------------------------+----------------------------------------------------------------+ 22 | | :doc:`SpongeVanilla ` | Mojang's "vanilla" Minecraft: Java Edition | 23 | +--------------------------------------+----------------------------------------------------------------+ 24 | 25 | 26 | Which do I choose? 27 | ~~~~~~~~~~~~~~~~~~ 28 | 29 | If you want to run MinecraftForge mods or you prefer to use Sponge in singleplayer, then choose 30 | :doc:`SpongeForge `. 31 | 32 | If you only want to run a Minecraft server with plugins on it (but no mods), then you can choose 33 | :doc:`SpongeForge ` or :doc:`SpongeVanilla `. SpongeForge supports vanilla clients, as long 34 | as you don't install Forge mods which require client-side mods. If you prefer to run a server without Forge, then 35 | SpongeVanilla is your preferred option. 36 | 37 | SpongeVanilla and SpongeForge (without mods) behave the same, so the decision between the two is a matter of preference, 38 | not a choice of functionality or features. 39 | 40 | Contents 41 | ======== 42 | 43 | .. toctree:: 44 | :maxdepth: 2 45 | :titlesonly: 46 | 47 | spongeforge 48 | spongevanilla 49 | -------------------------------------------------------------------------------- /source/plugin/index.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | Creating a Plugin 3 | ================= 4 | 5 | This section is intended for developers who wish to develop plugins with SpongeAPI. The articles cover various 6 | aspects of SpongeAPI and the concepts behind it. It is important to understand that the intent of this section is 7 | to help developers get started with SpongeAPI, not to cover every concept. The 8 | `Javadocs `__ will be of great help to you once you are comfortable with the API. 9 | 10 | .. note:: 11 | 12 | If you are familiar with SpongeAPI 7 and need assistance migrating your plugin to SpongeAPI 8 or later, see 13 | :doc:`migrating-from-7-to-8`. 14 | 15 | .. note:: 16 | 17 | It is suggested to have prior experience with developing in Java! It is also highly recommended to take code 18 | examples from the documentation as purely educational resources, as copying-and-pasting examples from the 19 | documentation likely will not work, especially without modification. 20 | 21 | .. tip:: 22 | 23 | The `Test Plugin Suite `__ is a collection of 24 | fully functional plugins that each demonstrate a specific part of the SpongeAPI. These plugin "recipes" are 25 | standalone and are compilable via Gradle or Maven. 26 | 27 | Contents 28 | ======== 29 | 30 | .. toctree:: 31 | :maxdepth: 2 32 | :titlesonly: 33 | 34 | api-versions 35 | migrating-from-7-to-8 36 | buildsystem 37 | workspace/index 38 | project/index 39 | plugin-identifier 40 | plugin-class 41 | lifecycle 42 | injection 43 | practices/index 44 | optional/index 45 | logging 46 | text/index 47 | commands/index 48 | event/index 49 | configuration/index 50 | data/index 51 | blocks/index 52 | entities/index 53 | items/index 54 | inventory/index 55 | trade-offers 56 | effects 57 | scheduler 58 | services 59 | database 60 | permissions 61 | bans 62 | metrics 63 | bookview 64 | economy/index 65 | placeholders/index 66 | wgen/index 67 | manager 68 | game-profile-manager 69 | offline-userplayer-data 70 | tab-lists 71 | plugin-meta 72 | ray-tracing 73 | debugging 74 | tutorials 75 | internals/index 76 | -------------------------------------------------------------------------------- /source/plugin/text/representations/index.rst: -------------------------------------------------------------------------------- 1 | ================ 2 | Text Serializers 3 | ================ 4 | 5 | .. javadoc-import:: 6 | net.kyori.adventure.text.Component 7 | net.kyori.adventure.text.serializer.ComponentSerializer 8 | net.kyori.adventure.text.serializer.gson.GsonComponentSerializer 9 | net.kyori.adventure.text.serializer.legacy.LegacyComponentSerializer 10 | net.kyori.adventure.text.serializer.plain.PlainTextComponentSerializer 11 | net.kyori.adventure.serializer.configurate4.ConfigurateComponentSerializer 12 | java.lang.String 13 | 14 | .. 15 | Note to editors: There used to be many other files in this folder, which were made irrelevant. 16 | This file was not moved to keep the URLs to this page alive. 17 | 18 | :javadoc:`ComponentSerializer`\ s provide a convenient way to serialize and de-serialize :javadoc:`Component` instances. 19 | There are four applicable formats: 20 | 21 | * Unformatted string - :javadoc:`PlainTextComponentSerializer` 22 | * Legacy ``&`` or ``§`` formatting - :javadoc:`LegacyComponentSerializer` 23 | * Configurate nodes - :javadoc:`ConfigurateComponentSerializer` 24 | * Minecraft JSON - :javadoc:`GsonComponentSerializer` 25 | 26 | For a full documentation of each serializer, see the Adventure docs' `AdventureSerializer`_ section. 27 | 28 | Serializing Text 29 | ~~~~~~~~~~~~~~~~ 30 | 31 | To serialize a ``Component`` object, simply use the :javadoc:`ComponentSerializer#serialize(Component)` 32 | method, providing the text object as the only argument. 33 | The method will return a serializer-specific object representing the ``Component``. 34 | For example, `ConfigurateComponentSerializer` will return a ``ConfigurationNode`` object. 35 | 36 | Deserializing to Text 37 | ~~~~~~~~~~~~~~~~~~~~~ 38 | 39 | To deserialize a ``String`` or other serialized object into its corresponding ``Component``, simply use the 40 | :javadoc:`ComponentSerializer#deserialize(R)` method, specifying the serialized object from above as the only argument. If the 41 | input is incorrectly formatted, an exception will be thrown. Alternatively, use the 42 | :javadoc:`ComponentSerializer#deserializeOr(R, Component)` method to deserialize without any exceptions. If there is an 43 | error, the second argument will be returned as a fallback. 44 | 45 | .. _AdventureSerializer: https://docs.papermc.io/adventure/serializer/ 46 | -------------------------------------------------------------------------------- /source/contributing/implementation/pr.rst: -------------------------------------------------------------------------------- 1 | ========================= 2 | Submitting a Pull-Request 3 | ========================= 4 | 5 | The Basics 6 | ========== 7 | 8 | First you need to setup your machine to be able to develop for and with Sponge: 9 | 10 | * read :doc:`/preparing/index` and setup your machine 11 | * get familiar with git and GitHub: :doc:`../howtogit` 12 | * read our :doc:`Code Style page ` and :doc:`../guidelines` 13 | * get familiar with our :doc:`git-implementation` 14 | 15 | When you're done and feel you're ready for developing Sponge, decide which parts you want to work on. 16 | 17 | Writing a PR 18 | ============ 19 | 20 | Fixing Bugs 21 | ~~~~~~~~~~~ 22 | 23 | Explain in a few sentences: 24 | 25 | * which bug you encountered, especially 26 | 27 | * how it behaved 28 | * how you think it should behave 29 | 30 | * what you fixed 31 | * how you fixed it 32 | 33 | Major API Addition 34 | ~~~~~~~~~~~~~~~~~~ 35 | 36 | So, you've developed a pretty large API addition that you want to now submit as a PR. Good! Constructive PR's are what 37 | make this project keep getting better. Which brings us to writing the glorious PR description. 38 | 39 | There have been a few in the past that go above and beyond the standards, examples include: 40 | 41 | * `Inventory API PR `_ 42 | * `Data API PR `_ 43 | 44 | Of course, those examples are the extreme, but PR's that are accepted and provide as a good standard of what should be 45 | included in a PR description are: 46 | 47 | * `Event Filtering PR `_ 48 | * `Bans improvement API PR `_ 49 | 50 | A few things that can be taken from this: 51 | 52 | * Links to any implementation PRs in clear view at the top of the PR, this can be achieved with GitHub Markdown 53 | 54 | .. code-block:: md 55 | 56 | *SpongeAPI* | [SpongeCommon](html link) | [SpongeDocs](html link) 57 | 58 | 59 | * Clear description of what the API PR is aiming to do, this can be a brief summary as if writing an essay, at most 4 60 | sentences long, depending on what the functionality is. 61 | 62 | * Clear code examples of how plugins can use the new feature (and if there are old features existing, why they needed 63 | to be changed). 64 | -------------------------------------------------------------------------------- /source/plugin/blocks/virtualblock.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | Virtual Block Changes 3 | ===================== 4 | 5 | .. javadoc-import:: 6 | org.spongepowered.math.vector.Vector3i 7 | org.spongepowered.api.block.BlockState 8 | org.spongepowered.api.effect.Viewer 9 | org.spongepowered.api.world.BlockChangeFlags 10 | 11 | Virtual block changes allow you to make it seem as if a block has changed on the client without actually changing any 12 | physical blocks in the world. 13 | 14 | Sending a virtual block change to the client is as simple as calling the 15 | :javadoc:`Viewer#sendBlockChange(int, int, int, BlockState)` method. You will need to specify the co-ordinates of the 16 | block that you wish to change, as well as the new :javadoc:`BlockState`. An example is shown below: 17 | 18 | .. code-block:: java 19 | 20 | import org.spongepowered.api.block.BlockTypes; 21 | import org.spongepowered.api.effect.Viewer; 22 | 23 | viewer.sendBlockChange(0, 65, 0, BlockTypes.COMMAND_BLOCK.getDefaultState()); 24 | 25 | This will make it seem as if the block at the co-ordinates ``0, 65, 0`` has changed to a command block. Of course, you 26 | are not restricted to the default state of a block. Any ``BlockState`` is accepted by the ``sendBlockChange()`` method. 27 | 28 | Besides specifying three integers for the co-ordinates, you may also specify a ``Vector3i``. An example of using the 29 | :javadoc:`Viewer#sendBlockChange(Vector3i, BlockState)` method is shown below: 30 | 31 | .. code-block:: java 32 | 33 | import org.spongepowered.math.vector.Vector3i; 34 | 35 | Vector3i vector = new Vector3i(0, 65, 0); 36 | viewer.sendBlockChange(vector, BlockTypes.COMMAND_BLOCK.getDefaultState()); 37 | 38 | .. tip:: 39 | 40 | If you wish to send a virtual block to all clients, you can now use :javadoc:`BlockChangeFlags#NOTIFY_CLIENTS` 41 | 42 | Resetting Changes 43 | ~~~~~~~~~~~~~~~~~ 44 | 45 | To reset any changes you've made to the client at a specific location, you can call the 46 | :javadoc:`Viewer#resetBlockChange(int, int, int)` method. For example, to undo our damage from the previous example, we 47 | can call the ``resetBlockChange()`` method specifying the co-ordinates from before: 48 | 49 | .. code-block:: java 50 | 51 | viewer.resetBlockChange(0, 65, 0); 52 | 53 | Note that you may also use a ``Vector3i`` in place of the three integers with this method as well. 54 | -------------------------------------------------------------------------------- /source/about/assets.rst: -------------------------------------------------------------------------------- 1 | ========== 2 | Art Assets 3 | ========== 4 | 5 | This page provides the official SpongePowered logo and mascot. The font used in the logo is *Montserrat*. Feel free to 6 | use them to spread the word about Sponge. 7 | However, note that these images are **not** provided under the MIT License, but rather are held under the 8 | `Creative Commons - Non Commercial, No Derivatives license `_. 9 | Refer to below for a clarification of our desires. 10 | 11 | .. note:: 12 | If you're reading a translated version, please note that the English license is the one which counts. Translated 13 | licenses are only provided for informational purposes. 14 | 15 | You may: 16 | 17 | * Make minor modifications to Spongie’s facial expressions - such as making a cute smile, 18 | making her perplexed or sad, adding a hat, and so on. It should be easily recognizable that the Spongie you create 19 | is the Spongie mascot, but wearing a different expression or clothing. 20 | 21 | * Use Spongie or the SpongePowered logo in an article or blog post about the Sponge project, and to spread the word. 22 | 23 | * Use the SpongePowered Logo to link to `Sponge Homepage `__ 24 | (for example in your signature on forums etc.) or other official SpongePowered resources. 25 | 26 | * Use the logos in social buttons. 27 | 28 | You may not: 29 | 30 | * Use the mascot as a link to the Sponge project only. The SpongePowered logo (which retains Spongie’s form) is a better 31 | representation of the Sponge project when used as an affiliate or reference. 32 | 33 | * Create a vastly modified version of Spongie, where she becomes unrecognizable or clearly different from the original 34 | Spongie mascot. 35 | 36 | * Add your project image to Spongie or the logo, nor vice versa. 37 | 38 | * Claim Spongie as your mascot, nor use her as a mascot for your own project. 39 | 40 | * Sell or use Spongie or the logo in commerce without permission. 41 | 42 | * Change any colors or dimensions. 43 | 44 | 45 | The Official Sponge Logo 46 | ~~~~~~~~~~~~~~~~~~~~~~~~ 47 | 48 | .. image:: /images/logo-spongepowered.png 49 | :align: center 50 | :alt: official SpongePowered logo 51 | 52 | Spongie - The Official Sponge Mascot 53 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 54 | 55 | .. image:: /images/logo-spongie.png 56 | :align: center 57 | :alt: Spongie the SpongePowered mascot 58 | -------------------------------------------------------------------------------- /source/plugin/commands/commandmanager.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Command Manager 3 | =============== 4 | 5 | .. javadoc-import:: 6 | org.spongepowered.api.command.manager.CommandManager 7 | org.spongepowered.api.event.lifecycle.RegisterCommandEvent 8 | 9 | 10 | The :javadoc:`CommandManager` stands as the manager for watching what commands get typed into chat, and redirecting them 11 | to the right command handler. To register your commands, use the :javadoc:`RegisterCommandEvent` as shown on 12 | :doc:`./commandbuilding`. 13 | 14 | Command Execution 15 | ~~~~~~~~~~~~~~~~~ 16 | 17 | When executing a command Sponge splits the sender into three categories. 18 | 19 | The first category is the ``permissions subject`` which is the target to 20 | check permissions for. The second cateogory is the ``audience`` which is 21 | the target for all messages to be sent to. With the last category being 22 | the actual ``sender`` who is the object that sent the command. 23 | 24 | .. warning:: 25 | 26 | When executing a command programmatically, you need to specifiy the permissions 27 | subject and the audience but not the sender as by default the sender will be 28 | the permissions manager. 29 | 30 | The command sender can be changed by pushing the new sender to the root of the 31 | cause stack. 32 | 33 | 34 | Sending a Command As a Player 35 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 36 | 37 | .. code-block:: java 38 | 39 | ServerPlayer player; 40 | 41 | Sponge.server().causeStackManager().pushCause(player); 42 | CommandManager cmdManager = Sponge.server().commandManager(); 43 | cmdManager.process(player, "msg Notch hi notch!"); 44 | 45 | Sending a Command As a Console 46 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 47 | 48 | .. code-block:: java 49 | 50 | SystemSubject console = Sponge.systemSubject(); 51 | 52 | Sponge.server().causeStackManager().pushCause(console); 53 | CommandManager cmdManager = Sponge.server().commandManager(); 54 | cmdManager.process(console, "kill Notch"); 55 | 56 | Sending a Command As a Player With Console Permissions 57 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 58 | 59 | .. code-block:: java 60 | 61 | ServerPlayer player; 62 | SystemSubject console = Sponge.systemSubject(); 63 | 64 | Sponge.server().causeStackManager().pushCause(player); 65 | CommandManager cmdManager = Sponge.server().commandManager(); 66 | cmdManager.process(console, player, "kill Notch"); -------------------------------------------------------------------------------- /source/preparing/text.rst: -------------------------------------------------------------------------------- 1 | ======================== 2 | Installing a Text Editor 3 | ======================== 4 | 5 | Articles on SpongeDocs are saved as text files in the `reStructuredText `_ markup 6 | language. Although your operating system's default text editor is likely sufficient for editing these files, installing 7 | a different text editor may prove to be useful. 8 | 9 | Downloads 10 | ========= 11 | 12 | Visual Studio Code 13 | ~~~~~~~~~~~~~~~~~~ 14 | 15 | VS Code is a cross platform, open source, code and text editor by Microsoft licensed under the MIT license. It is a popular 16 | choice used by many of Sponge's developers, for writing documentation and even for developing plugins. Unlike a regular text 17 | editor there is support for debugging, syntax highlighting, intelligent code completion, code refactoring, and more. There 18 | is also `Git support `_, a great plugin for 19 | `reST support `_, and even 20 | a plugin for `HOCON `_. 21 | 22 | **VS Code** can be downloaded for free from https://code.visualstudio.com/. 23 | 24 | Atom 25 | ~~~~ 26 | 27 | Atom is an open-source text editor published under the MIT license. Atom has built-in support for projects stored in a 28 | Git repository, such as SpongeDocs. `This article `_ goes more in 29 | depth about the features of Atom's Git integration. If you're interested in adding reST support to Atom, check out 30 | `this package `__. 31 | 32 | **Atom** can be downloaded for free from https://atom.io/. 33 | 34 | Notepad++ 35 | ~~~~~~~~~ 36 | 37 | Notepad++ is, arguably, one of the most popular text editors. 38 | 39 | **Notepad++** can be downloaded for free from https://notepad-plus-plus.org/. 40 | 41 | Sublime Text 42 | ~~~~~~~~~~~~ 43 | 44 | Sublime Text is a multi-platform text editor, with quite a few useful features. It includes the ability to customize the 45 | look of the editor, create useful macros, and even includes a plugin API to make your editing even easier. Sublime Text 46 | provides both a free version and a paid version. 47 | 48 | **Sublime Text** can be downloaded for free from https://www.sublimetext.com/ 49 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | 5 | # C extensions 6 | *.so 7 | 8 | # Distribution / packaging 9 | .Python 10 | env/ 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | lib/ 17 | lib64/ 18 | parts/ 19 | sdist/ 20 | var/ 21 | venv/ 22 | *.egg-info/ 23 | .installed.cfg 24 | *.egg 25 | 26 | # PyInstaller 27 | # Usually these files are written by a python script from a template 28 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 29 | *.manifest 30 | *.spec 31 | 32 | # Installer logs 33 | pip-log.txt 34 | pip-delete-this-directory.txt 35 | 36 | # Unit test / coverage reports 37 | htmlcov/ 38 | .tox/ 39 | .coverage 40 | .cache 41 | nosetests.xml 42 | coverage.xml 43 | 44 | # Translations 45 | *.mo 46 | *.pot 47 | 48 | # Django stuff: 49 | *.log 50 | 51 | # Sphinx documentation 52 | docs/_build/ 53 | build/ 54 | 55 | # PyBuilder 56 | target/ 57 | *.pydevproject 58 | .metadata 59 | .gradle 60 | bin/ 61 | tmp/ 62 | *.tmp 63 | *.bak 64 | *.swp 65 | *~.nib 66 | local.properties 67 | .settings/ 68 | .loadpath 69 | 70 | # External tool builders 71 | .externalToolBuilders/ 72 | 73 | # Locally stored "Eclipse launch configurations" 74 | *.launch 75 | 76 | # CDT-specific 77 | .cproject 78 | 79 | # PDT-specific 80 | .buildpath 81 | 82 | # eclipse 83 | .project 84 | .classpath 85 | .factorypath 86 | 87 | # sbteclipse plugin 88 | .target 89 | 90 | # TeXlipse plugin 91 | .texlipse 92 | *.pydevproject 93 | .metadata 94 | .gradle 95 | bin/ 96 | tmp/ 97 | *.tmp 98 | *.bak 99 | *.swp 100 | *~.nib 101 | local.properties 102 | .settings/ 103 | .loadpath 104 | 105 | # External tool builders 106 | .externalToolBuilders/ 107 | 108 | # Locally stored "Eclipse launch configurations" 109 | *.launch 110 | 111 | # CDT-specific 112 | .cproject 113 | 114 | # PDT-specific 115 | .buildpath 116 | 117 | # sbteclipse plugin 118 | .target 119 | 120 | # TeXlipse plugin 121 | .texlipse 122 | 123 | # Sphinx 124 | _build 125 | 126 | .idea/ 127 | *.iml 128 | 129 | # Transifex config 130 | .tx/ 131 | 132 | # Node 133 | node_modules/ 134 | 135 | # Source code created by pip 136 | src/ 137 | 138 | # Any javadoc link dumps provided by sphinx-JDLinker. 139 | javadoc_dump.txt 140 | 141 | # OS Files 142 | .DS_Store 143 | 144 | locale 145 | 146 | # SpongeDocs 147 | deployment/Dockerfile 148 | docker-compose.yml 149 | -------------------------------------------------------------------------------- /tools/code-checker/src/main/java/org/spongepowered/docs/tools/codeblock/KeywordBasedDeIndenter.java: -------------------------------------------------------------------------------- 1 | /* 2 | * This file is part of SpongeAPI, licensed under the MIT License (MIT). 3 | * 4 | * Copyright (c) SpongePowered 5 | * Copyright (c) contributors 6 | * 7 | * Permission is hereby granted, free of charge, to any person obtaining a copy 8 | * of this software and associated documentation files (the "Software"), to deal 9 | * in the Software without restriction, including without limitation the rights 10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 | * copies of the Software, and to permit persons to whom the Software is 12 | * furnished to do so, subject to the following conditions: 13 | * 14 | * The above copyright notice and this permission notice shall be included in 15 | * all copies or substantial portions of the Software. 16 | * 17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 | * THE SOFTWARE. 24 | */ 25 | package org.spongepowered.docs.tools.codeblock; 26 | 27 | import static java.util.Objects.requireNonNull; 28 | 29 | import java.util.function.Predicate; 30 | import java.util.function.UnaryOperator; 31 | 32 | public class KeywordBasedDeIndenter implements UnaryOperator { 33 | 34 | private final Predicate keywordPredicate; 35 | private int indentionLevel = 0; 36 | 37 | public KeywordBasedDeIndenter(Predicate keywordPredicate) { 38 | this.keywordPredicate = requireNonNull(keywordPredicate, "keywordPredicate"); 39 | } 40 | 41 | @Override 42 | public String apply(String text) { 43 | if (this.keywordPredicate.test(text)) { 44 | this.indentionLevel = 0; 45 | while (text.charAt(this.indentionLevel) == ' ') { 46 | this.indentionLevel++; 47 | } 48 | } 49 | for (int i = 0; i < this.indentionLevel && !text.isEmpty() && text.charAt(0) == ' '; i++) { 50 | text = text.substring(1); 51 | } 52 | return text; 53 | } 54 | 55 | } 56 | -------------------------------------------------------------------------------- /source/plugin/internals/implementation.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | Internal Sponge Classes 3 | ======================= 4 | 5 | .. warning:: 6 | These docs were written for SpongeAPI 7 and are likely out of date. 7 | `If you feel like you can help update them, please submit a PR! `__ 8 | 9 | You can add SpongeCommon, SpongeVanilla or SpongeForge as a dependency to your plugin project if you need to access 10 | internal Sponge classes. 11 | 12 | .. warning:: 13 | You should only add a specific implementation dependency when really necessary. If possible, use SpongeAPI or 14 | request feature additions on the `SpongeAPI issue tracker `_. 15 | 16 | In addition to the normal artifacts, the implementation modules provide a ``dev`` artifact which can be easily used in 17 | the IDE, since it is not re-obfuscated. All implementation modules have the API module already included, so you do not 18 | need an extra dependency on SpongeAPI. 19 | 20 | SpongeCommon 21 | ------------ 22 | 23 | - **Group ID**: ``org.spongepowered`` 24 | - **Artifact ID**: ``spongecommon`` 25 | - **Version**: Same as SpongeAPI + current recommended version (see :doc:`/versions/versioning` for details) 26 | - **Classifier**: ``dev`` 27 | 28 | Example Using Gradle 29 | ```````````````````` 30 | 31 | .. code-block:: groovy 32 | 33 | dependencies { 34 | compile 'org.spongepowered:spongecommon:7.1.0:dev' 35 | } 36 | 37 | SpongeVanilla 38 | ------------- 39 | 40 | Choose a build from the downloads page and copy the full version string to your dependency definition. 41 | 42 | - **Group ID**: ``org.spongepowered`` 43 | - **Artifact ID**: ``spongevanilla`` 44 | - **Version**: Use a build version from the downloads page 45 | - **Classifier**: ``dev`` 46 | 47 | Example Using Gradle 48 | ```````````````````` 49 | 50 | .. code-block:: groovy 51 | 52 | dependencies { 53 | compile 'org.spongepowered:spongevanilla:1.12.2-7.1.1-RC123:dev' 54 | } 55 | 56 | SpongeForge 57 | ----------- 58 | 59 | Choose a build from the downloads page and copy the full version string to your dependency definition. 60 | 61 | - **Group ID**: ``org.spongepowered`` 62 | - **Artifact ID**: ``spongeforge`` 63 | - **Version**: Use a build version from the downloads page 64 | - **Classifier**: ``dev`` 65 | 66 | Example Using Gradle 67 | ```````````````````` 68 | 69 | .. code-block:: groovy 70 | 71 | dependencies { 72 | compile 'org.spongepowered:spongeforge:1.12.2-2768-7.1.1-RC3484:dev' 73 | } 74 | -------------------------------------------------------------------------------- /source/plugin/bookview.rst: -------------------------------------------------------------------------------- 1 | ========== 2 | Book Views 3 | ========== 4 | 5 | .. javadoc-import:: 6 | net.kyori.adventure.text.Component 7 | org.spongepowered.api.effect.Viewer 8 | org.spongepowered.api.item.inventory.ItemStack 9 | org.spongepowered.api.text.BookView 10 | org.spongepowered.api.text.BookView.Builder 11 | java.util.Collection 12 | 13 | A :javadoc:`BookView` is the representation of the Book GUI on the client. The ``BookView`` is not associated with an 14 | actual :javadoc:`ItemStack` and is only for displaying :javadoc:`Component` through a book to the player. Note that a 15 | ``BookView`` is read-only, due to it being impossible to tell the client to open an unsigned book. 16 | 17 | To create a ``BookView``, we simply need to obtain a :javadoc:`BookView.Builder`, which is provided through the 18 | :javadoc:`BookView#builder()` method. Using the builder, we can specify the title, the author, and the pages of the 19 | ``BookView``. Then to use the view, we have to send it to a :javadoc:`Viewer`. An example of this is shown below: 20 | 21 | .. code-block:: java 22 | 23 | import net.kyori.adventure.text.Component; 24 | import org.spongepowered.api.effect.Viewer; 25 | import org.spongepowered.api.text.BookView; 26 | 27 | BookView bookView = BookView.builder() 28 | .title(Component.text("Story Mode")) 29 | .author(Component.text("Notch")) 30 | .addPage(Component.text("There once was a Steve...")) 31 | .build(); 32 | viewer.sendBookView(bookView); 33 | 34 | This will display a book to the client with a single page that contains the text specified in the 35 | :javadoc:`BookView.Builder#addPage(Component)` method. Of course, you don't have to call ``addPage(Component)`` for every page 36 | you wish to add. The ``BookView.Builder`` class provides a :javadoc:`BookView.Builder#addPages(Collection)` 37 | method that accepts multiple ``Component``\ s. 38 | 39 | The ``BookView.Builder`` class also provides the :javadoc:`BookView.Builder#insertPage(int, Component)` and the corresponding 40 | :javadoc:`BookView.Builder#insertPages(int, Collection)` methods for inserting a page or several pages at any 41 | given index. 42 | 43 | You may also remove pages of a ``BookView`` by providing either the ``Component`` from the page or by specifying the index 44 | of the page that you wish to remove. You simply need to use the corresponding 45 | :javadoc:`BookView.Builder#removePage(Component)`, :javadoc:`BookView.Builder#removePage(int)`, or 46 | :javadoc:`BookView.Builder#removePages(Collection)` methods. 47 | -------------------------------------------------------------------------------- /source/ore/routes/user.rst: -------------------------------------------------------------------------------- 1 | ======== 2 | Get User 3 | ======== 4 | 5 | **GET /api/v1/users/:username** 6 | 7 | Returns a single user. 8 | 9 | **Sample output:** 10 | 11 | .. code-block:: json 12 | 13 | { 14 | "id": 26141, 15 | "createdAt": "2016-12-31 02:20:59.63", 16 | "username": "blood", 17 | "roles": [ 18 | "Sponge Staff", 19 | "Sponge Developer", 20 | "Sponge Leader" 21 | ], 22 | "starred": [], 23 | "avatarUrl": "https://www.gravatar.com/avatar/9d9369d67c6f5d2c5f9d3b0d195a55f9", 24 | "projects": [{ 25 | "pluginId": "griefprevention", 26 | "createdAt": "2017-01-29 03:28:16.978", 27 | "name": "GriefPrevention", 28 | "owner": "blood", 29 | "description": "This plugin is designed to prevent all forms of grief.", 30 | "href": "/blood/GriefPrevention", 31 | "members": [{ 32 | "userId": 26141, 33 | "name": "blood", 34 | "roles": ["Owner"], 35 | "headRole": "Owner" 36 | }], 37 | "channels": [{ 38 | "name": "Release", 39 | "color": "#009600" 40 | }], 41 | "recommended": { 42 | "id": 1277, 43 | "createdAt": "2018-02-25 22:17:57.018", 44 | "name": "1.12.2-4.3.0.555", 45 | "dependencies": [{ 46 | "pluginId": "spongeapi", 47 | "version": "7.1.0-SNAPSHOT-6aa4e438" 48 | }], 49 | "pluginId": "griefprevention", 50 | "channel": { 51 | "name": "Release", 52 | "color": "#009600" 53 | }, 54 | "fileSize": 919256, 55 | "md5": "e1a1603f59f6a74edf5ea3ef8183361a", 56 | "staffApproved": true, 57 | "href": "/blood/GriefPrevention/versions/1.12.2-4.3.0.555", 58 | "tags": [{ 59 | "id": 42, 60 | "name": "Sponge", 61 | "data": "7.1.0-SNAPSHOT-6aa4e438", 62 | "backgroundColor": "#F7Cf0D", 63 | "foregroundColor": "#000000" 64 | }], 65 | "downloads": 24, 66 | "author": "blood" 67 | }, 68 | "category": { 69 | "title": "Protection", 70 | "icon": "fa-lock" 71 | }, 72 | "views": 4208, 73 | "downloads": 2727, 74 | "stars": 30 75 | }] 76 | } 77 | -------------------------------------------------------------------------------- /tools/code-checker/src/test/java/org/spongepowered/docs/tools/codeblock/FileCheckerTest.java: -------------------------------------------------------------------------------- 1 | package org.spongepowered.docs.tools.codeblock; 2 | 3 | import static java.nio.charset.StandardCharsets.UTF_8; 4 | import static org.junit.jupiter.api.Assertions.assertTrue; 5 | 6 | import java.io.BufferedReader; 7 | import java.io.File; 8 | import java.io.FileInputStream; 9 | import java.io.FileOutputStream; 10 | import java.io.IOException; 11 | import java.io.InputStream; 12 | import java.io.InputStreamReader; 13 | import java.io.OutputStream; 14 | 15 | import org.junit.jupiter.api.Test; 16 | 17 | class FileCheckerTest { 18 | 19 | @Test 20 | void test() throws IOException { 21 | File testRunDir = new File("target/test-run"); 22 | testRunDir.mkdirs(); 23 | File inFile = new File(testRunDir, "TestFile.rst"); 24 | copyResourceToFile("/TestFile.rst", inFile); 25 | FileChecker checker = new FileChecker(inFile, inFile.getParent().length() + 1, testRunDir); 26 | // assertEquals(12, checker.process()); 27 | checker.process(); 28 | 29 | boolean match = true; 30 | File outputFile = new File(testRunDir, "Code_TestFile.java"); 31 | try (InputStream fis = new FileInputStream(outputFile); 32 | InputStreamReader fir = new InputStreamReader(fis, UTF_8); 33 | BufferedReader reader1 = new BufferedReader(fir); 34 | InputStream ris = getClass().getResourceAsStream("/Code_TestFile.java"); 35 | InputStreamReader rir = new InputStreamReader(ris, UTF_8); 36 | BufferedReader reader2 = new BufferedReader(rir)) { 37 | String line1, line2; 38 | while ((line1 = reader1.readLine()) != null & (line2 = reader2.readLine()) != null) { 39 | if (!line1.equals(line2)) { 40 | match = false; 41 | break; 42 | } 43 | } 44 | if (line1 != null) { 45 | match = false; 46 | } 47 | if (line2 != null) { 48 | match = false; 49 | } 50 | } 51 | if (!match) { 52 | copyResourceToFile("/Code_TestFile.java", new File(testRunDir, "expectedCode_TestFile.java")); 53 | } 54 | assertTrue(match, "Generated file does not match expected one"); 55 | } 56 | 57 | private void copyResourceToFile(String resourcePath, File target) throws IOException { 58 | try (InputStream stream = getClass().getResourceAsStream(resourcePath); 59 | OutputStream fos = new FileOutputStream(target)) { 60 | stream.transferTo(fos); 61 | } 62 | } 63 | 64 | } 65 | -------------------------------------------------------------------------------- /tools/code-checker/src/test/java/org/spongepowered/docs/tools/codeblock/RepeatedKeywordPredicateTest.java: -------------------------------------------------------------------------------- 1 | /* 2 | * This file is part of SpongeAPI, licensed under the MIT License (MIT). 3 | * 4 | * Copyright (c) SpongePowered 5 | * Copyright (c) contributors 6 | * 7 | * Permission is hereby granted, free of charge, to any person obtaining a copy 8 | * of this software and associated documentation files (the "Software"), to deal 9 | * in the Software without restriction, including without limitation the rights 10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 | * copies of the Software, and to permit persons to whom the Software is 12 | * furnished to do so, subject to the following conditions: 13 | * 14 | * The above copyright notice and this permission notice shall be included in 15 | * all copies or substantial portions of the Software. 16 | * 17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 | * THE SOFTWARE. 24 | */ 25 | package org.spongepowered.docs.tools.codeblock; 26 | 27 | import static org.junit.jupiter.api.Assertions.assertEquals; 28 | 29 | import java.util.Arrays; 30 | import java.util.stream.Collectors; 31 | import java.util.stream.Stream; 32 | 33 | import org.junit.jupiter.api.Test; 34 | 35 | class RepeatedKeywordPredicateTest { 36 | 37 | @Test 38 | void test() { 39 | assertEquals(Arrays.asList("Fire", "destroyed"), 40 | Stream.of("Foo", "Bar", "ON", "Fire", "OFF", "was", "destroyed") 41 | .filter(new RepeatedKeywordPredicate<>(s -> s.length() > 3, 1)) 42 | .collect(Collectors.toList())); 43 | 44 | assertEquals(Arrays.asList(), 45 | Stream.of("Foo", "Bar", "OFF", "Fire", "OFF", "was", "destroyed") 46 | .filter(new RepeatedKeywordPredicate<>(s -> s.length() > 4, 2)) 47 | .collect(Collectors.toList())); 48 | 49 | assertEquals(Arrays.asList("Fire", "ON", "was", "destroyed"), 50 | Stream.of("Foo", "Bar", "ON", "Fire", "ON", "was", "destroyed") 51 | .filter(new RepeatedKeywordPredicate<>(s -> s.length() >= 2, 4)) 52 | .collect(Collectors.toList())); 53 | } 54 | 55 | } 56 | -------------------------------------------------------------------------------- /source/plugin/commands/childcommands.rst: -------------------------------------------------------------------------------- 1 | ============== 2 | Child Commands 3 | ============== 4 | 5 | .. javadoc-import:: 6 | org.spongepowered.api.command.Command.Builder 7 | org.spongepowered.api.command.CommandExecutor 8 | org.spongepowered.api.command.exception.ArgumentParseException 9 | java.lang.String 10 | 11 | The :javadoc:`Builder` supports hierarchical command structure like this: 12 | 13 | - ``/mail`` (parent command) 14 | - ``/mail send`` (child command) 15 | - ``/mail read`` (child command) 16 | 17 | Every child command is a separate ``Command`` and can be created in the same way as a regular command is. 18 | 19 | .. code-block:: java 20 | 21 | import org.spongepowered.api.command.Command; 22 | 23 | Command.Paramertized readCmd = Command 24 | .builder() 25 | .permission("myplugin.mail.read") 26 | .shortDescription(Component.text("Read your inbox")) 27 | .executor(...) 28 | .build(); 29 | 30 | Command.Paramertized sendCmd = Command 31 | .builder() 32 | .permission("myplugin.mail.send") 33 | .shortDescription(Component.text("Send a mail")) 34 | .addParameter(...) 35 | .executor(...) 36 | .build(); 37 | 38 | Instead of registering them to the event, child commands are registered on their parent command using the 39 | :javadoc:`Builder#addChild(Command, String, String...)` method. They are registered with a list of aliases. 40 | The first alias supplied is the primary one and will appear in the usage message. 41 | 42 | .. code-block:: java 43 | 44 | Command.Paramertized mailCommand = Command.builder() 45 | .permission("myplugin.mail.base") 46 | .shortDescription(Component.text("Send and receive mails")) 47 | .child(readCmd, "read", "r", "inbox") 48 | .child(sendCmd, "send", "s", "write") 49 | .build(); 50 | 51 | Fallback Behavior 52 | ================= 53 | 54 | If a command has child commands, a :javadoc:`CommandExecutor`, set through 55 | :javadoc:`Builder#executor(CommandExecutor)`, and the parameters for the executor become optional. 56 | 57 | What happens with errors in selection and argument parsing of child commands is dependent on whether this parent 58 | executor exists. If a parent executor has not been set, and if the requested child command could not be found or the 59 | arguments cannot be parsed, then an :javadoc:`ArgumentParseException` will be thrown. 60 | 61 | .. warning:: 62 | 63 | If an ``ArgumentParseException`` is not handled, then the Minecraft Brigadier system will tell the user that the 64 | command doesn't exist. 65 | 66 | If the child executor throws an exception, the fallback executor is not executed and the error message from the child 67 | executor is displayed. 68 | -------------------------------------------------------------------------------- /source/server/management/exploit-patches.rst: -------------------------------------------------------------------------------- 1 | =============== 2 | Exploit Patches 3 | =============== 4 | 5 | .. warning:: 6 | These docs were written for SpongeAPI 7 and are likely out of date. 7 | `If you feel like you can help update them, please submit a PR! `__ 8 | 9 | In recent Sponge builds (SpongeForge 974+), SpongeForge and SpongeVanilla patch a few client-server exploits. Whenever 10 | the implementations detect a user performing an exploit, they are kicked from the server with a message explaining why 11 | they were kicked. If enabled, a log message is also sent to the console. More exploit patches may be added in the 12 | future. 13 | 14 | .. note:: 15 | If you know about an exploit we currently *don't* cover, please let us know! You can contact us via 16 | `exploits@spongepowered.org `_ or PM a staff member on the forums. Please **DO NOT** post 17 | exploits publicly on IRC, our GitHub repos or the forums, if they're still unknown. This prevents abuse until we 18 | get the issues fixed. 19 | 20 | Exploits Patched implemented in Sponge 21 | ====================================== 22 | 23 | #. Sign command exploit where a client could run a command such as 'op' 24 | #. Client could force the server to make the user respawn invisible 25 | #. Client could set an itemstack's display name and cause it to exceed the character limit 26 | 27 | Note that these patches can't be disabled, only the logging is configurable as of now. 28 | 29 | .. warning:: 30 | The invisibility exploit patch has been disabled in recent Sponge builds due to the detection method falsely 31 | accusing users of performing the exploit. 32 | 33 | Log Message Control 34 | =================== 35 | 36 | Log messages for the exploit patches can be individually controlled in the Sponge config file. Please read the 37 | :doc:`../getting-started/configuration/sponge-conf` page for more information. Here's a short overview of available 38 | options: 39 | 40 | .. code-block:: guess 41 | 42 | # Log when server receives exploited packet with itemstack name exceeding string limit. 43 | exploit-itemstack-name-overflow=false 44 | 45 | # Log when player attempts to respawn invisible to surrounding players. 46 | exploit-respawn-invisibility=false 47 | 48 | # Log when server receives exploited packet to update a sign containing commands from player with no permission. 49 | exploit-sign-command-updates=false 50 | 51 | .. tip:: 52 | Log messages can also be controlled via a command, instead of directly editing the config file. For example, to 53 | enable the sign command exploit logging, type ``sponge config -g logging.exploit-sign-command-updates true`` in 54 | the console (You can also type the commands in-game if you are an op). 55 | -------------------------------------------------------------------------------- /tools/code-checker/src/test/java/org/spongepowered/docs/tools/codeblock/KeywordPartitionerTest.java: -------------------------------------------------------------------------------- 1 | /* 2 | * This file is part of SpongeAPI, licensed under the MIT License (MIT). 3 | * 4 | * Copyright (c) SpongePowered 5 | * Copyright (c) contributors 6 | * 7 | * Permission is hereby granted, free of charge, to any person obtaining a copy 8 | * of this software and associated documentation files (the "Software"), to deal 9 | * in the Software without restriction, including without limitation the rights 10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 | * copies of the Software, and to permit persons to whom the Software is 12 | * furnished to do so, subject to the following conditions: 13 | * 14 | * The above copyright notice and this permission notice shall be included in 15 | * all copies or substantial portions of the Software. 16 | * 17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 | * THE SOFTWARE. 24 | */ 25 | package org.spongepowered.docs.tools.codeblock; 26 | 27 | import static java.util.Arrays.asList; 28 | import static org.junit.jupiter.api.Assertions.assertEquals; 29 | import static org.spongepowered.docs.tools.codeblock.KeywordPartitioner.partition; 30 | 31 | import java.util.stream.Collectors; 32 | import java.util.stream.Stream; 33 | 34 | import org.junit.jupiter.api.Test; 35 | 36 | class KeywordPartitionerTest { 37 | 38 | @Test 39 | void test() { 40 | assertEquals(asList(asList("Foo", "Bar", "ON"), asList("OFF", "was")), 41 | partition( 42 | Stream.of("Foo", "Bar", "ON", "Fire", "OFF", "was", "destroyed"), 43 | s -> s.length() > 3) 44 | .collect(Collectors.toList())); 45 | 46 | assertEquals(asList(asList("Foo", "Bar", "OFF", "Fire", "OFF", "was")), 47 | partition( 48 | Stream.of("Foo", "Bar", "OFF", "Fire", "OFF", "was", "destroyed"), 49 | s -> s.length() > 4) 50 | .collect(Collectors.toList())); 51 | 52 | assertEquals(asList(asList(), asList(), asList("ON"), asList("ON"), asList()), 53 | partition( 54 | Stream.of("Foo", "Bar", "ON", "Fire", "ON", "was", "destroyed"), 55 | s -> s.length() > 2) 56 | .collect(Collectors.toList())); 57 | } 58 | 59 | } 60 | -------------------------------------------------------------------------------- /tools/code-checker/src/main/java/org/spongepowered/docs/tools/codeblock/KeywordRedirectingPredicate.java: -------------------------------------------------------------------------------- 1 | /* 2 | * This file is part of SpongeAPI, licensed under the MIT License (MIT). 3 | * 4 | * Copyright (c) SpongePowered 5 | * Copyright (c) contributors 6 | * 7 | * Permission is hereby granted, free of charge, to any person obtaining a copy 8 | * of this software and associated documentation files (the "Software"), to deal 9 | * in the Software without restriction, including without limitation the rights 10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 | * copies of the Software, and to permit persons to whom the Software is 12 | * furnished to do so, subject to the following conditions: 13 | * 14 | * The above copyright notice and this permission notice shall be included in 15 | * all copies or substantial portions of the Software. 16 | * 17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 | * THE SOFTWARE. 24 | */ 25 | package org.spongepowered.docs.tools.codeblock; 26 | 27 | import java.util.function.Consumer; 28 | import java.util.function.Predicate; 29 | 30 | /** 31 | * Filters all matching entries from the test and redirects them to a 32 | * {@link Consumer}. This predicate will always return the opposite of the 33 | * underlying {@link Predicate}. 34 | * 35 | * @param The type of data the predicate deals with. 36 | */ 37 | public class KeywordRedirectingPredicate implements Predicate { 38 | 39 | private final Predicate keywordPredicate; 40 | private final Consumer redirectionTarget; 41 | 42 | /** 43 | * Creates a new KeywordRedirectingPredicate using the given predicate as a 44 | * filter. The filtered entries will be redirected to the given consumer. 45 | * 46 | * @param keywordPredicate The predicate used to filter the input. 47 | * @param redirectionTarget The consumer that should receive the filtered 48 | * entries. 49 | */ 50 | public KeywordRedirectingPredicate(Predicate keywordPredicate, Consumer redirectionTarget) { 51 | this.keywordPredicate = keywordPredicate; 52 | this.redirectionTarget = redirectionTarget; 53 | }; 54 | 55 | @Override 56 | public boolean test(T t) { 57 | if (this.keywordPredicate.test(t)) { 58 | this.redirectionTarget.accept(t); 59 | return false; 60 | } else { 61 | return true; 62 | } 63 | } 64 | 65 | } 66 | -------------------------------------------------------------------------------- /source/about/introduction.rst: -------------------------------------------------------------------------------- 1 | ============ 2 | Introduction 3 | ============ 4 | 5 | What Is Sponge? 6 | ~~~~~~~~~~~~~~~ 7 | 8 | The purpose of the Sponge project is to create a plugin development framework for Minecraft: Java Edition. Sponge is 9 | being created by a global community, and its open-source nature means anyone can participate. 10 | 11 | Sponge was created after seeing the failures of other projects in the Minecraft plugin development community. We are 12 | trying to avoid making the same mistakes as other projects; thus: 13 | 14 | * Sponge is an extremely open project. 15 | * Sponge is licensed under the MIT license - an extremely permissive open source license. 16 | * Performance is of high priority. 17 | 18 | Most plugins developed with SpongeAPI should work across several different versions of Minecraft without needing to be 19 | updated. This means that, for the most part, server owners do not need to worry about plugin incompatibilities. 20 | 21 | We have two other projects in addition to SpongeAPI: 22 | 23 | (1) **SpongeForge**, a coremod for Minecraft Forge, which is an existing Minecraft: Java Edition modding framework 24 | famous for spurring the Minecraft modding scene. Forge lacks a cross-version API, and this is where Sponge steps 25 | in. Sponge allows server owners to deploy Sponge plugins with ease, making server management easier. 26 | 27 | (2) **SpongeVanilla**, a stand-alone implementation of SpongeAPI, running on top of the vanilla Minecraft server. 28 | (SpongeVanilla was formerly known as Granite, until the development teams merged). 29 | 30 | Players on servers running SpongeForge or SpongeVanilla do not need to install any client-side mods. They are able to join 31 | servers running Sponge using the vanilla Minecraft client provided by Mojang. 32 | 33 | SpongeAPI is not tied to any platform. This means that server owners can run Sponge plugins on any official 34 | implementation of SpongeAPI. Sponge plugins should function identically on either implementation, due to the 35 | common functionality of mixins. 36 | 37 | Where Can I Download Sponge? 38 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 39 | 40 | You can download SpongeForge and SpongeVanilla on our `downloads page `_. 41 | 42 | Who Is behind Sponge? 43 | ~~~~~~~~~~~~~~~~~~~~~ 44 | 45 | The project leaders are blood, gabizou and Zidane. We are trying to be very open with the team to ensure the project leaders 46 | do not end up “holding all the keys.” Nonetheless, these three people make the final decisions to ensure the efficient 47 | operation of the project. 48 | 49 | A full list of staff members is located at :doc:`staff`. 50 | 51 | Our developers are well-versed with Java, and many of them have worked with Minecraft for years and know the ins-and-outs 52 | of its mechanics. There are tons of very good developers working on the Sponge project, and it would be nearly impossible 53 | to list all of them! 54 | -------------------------------------------------------------------------------- /source/preparing/git.rst: -------------------------------------------------------------------------------- 1 | ============== 2 | Installing Git 3 | ============== 4 | 5 | Git is an open-source version control system, and helps tremendously with collaborative project development. 6 | 7 | The Sponge project, alongside thousands of other open-source projects, hosts its Git repositories on GitHub. Thus, 8 | Git is a crucial tool in the development of Sponge and SpongeAPI. 9 | 10 | The `Git website `__ has substantial documentation, and their downloads page offers a range 11 | of options for GUI clients suitable for various operating systems. 12 | 13 | Download 14 | ======== 15 | 16 | Windows 17 | ~~~~~~~ 18 | 19 | `GitHub Desktop `_ is an easy method of installing Git on Windows, because Git is 20 | included as a part of the software. 21 | 22 | Rebooting your computer after installing Git is recommended. 23 | 24 | Mac 25 | ~~~ 26 | 27 | There are a couple of ways to install Git on macOS. 28 | 29 | The easiest method is to install Xcode Command Line Tools. 30 | 31 | .. warning:: 32 | 33 | These instructions do not work on Macs running a version older than Mavericks. If you are running a version of OS X 34 | older than Mavericks, install the GitHub client instead. 35 | 36 | 1. Launch the Terminal. 37 | #. Run ``xcode-select --install``. 38 | #. Install it, and grab a cookie while you wait. 39 | #. Run ``git`` from the Terminal. 40 | 41 | Alternatively, you can install `GitHub Desktop `_. Git is available as a part of the GitHub 42 | Desktop installation. 43 | 44 | Rebooting your computer after installing Git is recommended. 45 | 46 | Linux and Unix 47 | ~~~~~~~~~~~~~~ 48 | 49 | The simplest method of installing Git on Linux is by using the package manager that came with your Linux distribution. 50 | 51 | .. note:: 52 | 53 | You may need to prefix these commands with ``sudo``. 54 | 55 | 1. Launch the Terminal. 56 | #. Run ``apt-get install git`` if you are on an Ubuntu or Debian-based distribution. Run ``yum install git`` if you are 57 | on Fedora. 58 | 59 | GitHub Desktop is currently not available for Linux, unlike Windows and Mac. 60 | 61 | Rebooting your computer after installing Git is recommended. 62 | 63 | Setup 64 | ===== 65 | 66 | Who Are You? 67 | ~~~~~~~~~~~~ 68 | 69 | Before you even start to work with git and the repository, make sure your 70 | git configuration has your identity set up. Open up your CLI and enter: 71 | 72 | .. code-block:: bash 73 | 74 | git config --list 75 | 76 | Look for ``user.name`` and ``user.email``. If they are not the same username and email as your GitHub account 77 | then set them: 78 | 79 | .. code-block:: bash 80 | 81 | git config --global user.name "John Doe" 82 | git config --global user.email johndoe@example.com 83 | 84 | 85 | .. tip:: 86 | 87 | Do not proceed with any contribution in any Sponge repository until you establish your ``user.name`` and ``user.email``. 88 | -------------------------------------------------------------------------------- /source/plugin/logging.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | Logging and Debugging 3 | ===================== 4 | 5 | There are a few logging frameworks available for use in Java. Logging is preferable to printing to stdout or stderr with 6 | ``System.out.println()`` for a number of reasons: 7 | 8 | * Logged messages are labeled with a source name, making it easier to figure out where the logged messages are coming from. 9 | * Logged messages have a severity level which allows for simple filtering (e.g. disable all non-critical notices). 10 | * The available logger frameworks allow you to enable or disable messages from certain sources. 11 | 12 | Sponge uses ``org.apache.logging.log4j.Logger``, not ``java.util.logging.Logger``. 13 | 14 | Getting a Logger 15 | ================ 16 | 17 | The Guice module used during the initialization of plugins has a plugin-scoped logger. This allows you to annotate a 18 | field, method, or constructor with ``@Inject`` to get the logger for your plugin, which is pre-configured with the 19 | correct plugin ID. 20 | 21 | .. note:: 22 | See :doc:`plugin-class` for information on configuring your plugin ID. 23 | 24 | **Example - Field** 25 | 26 | .. code-block:: java 27 | 28 | import com.google.inject.Inject; 29 | import org.apache.logging.log4j.Logger; 30 | 31 | @Inject 32 | private Logger logger; 33 | 34 | **Example - Method** 35 | 36 | .. code-block:: java 37 | 38 | private Logger logger; 39 | 40 | @Inject 41 | private void setLogger(Logger logger) { 42 | this.logger = logger; 43 | } 44 | 45 | **Example - Constructor** 46 | 47 | .. code-block:: java 48 | 49 | // For the purpose of this example, "Banana" is the class name 50 | 51 | private final Logger logger; 52 | 53 | @Inject 54 | public Banana(Logger logger) { 55 | this.logger = logger; 56 | } 57 | 58 | It is recommended to set your logger in your main plugin class, as it is instantiated with the Guice injector when the 59 | plugin is loaded. 60 | 61 | Creating a getter method for your logger in the same class in which it was set is also ideal, although optional. An 62 | example getter method is illustrated below. 63 | 64 | .. code-block:: java 65 | 66 | public Logger getLogger() { 67 | return logger; 68 | } 69 | 70 | Emitting Messages 71 | ================= 72 | 73 | Emitting a message with your logger is very simple. 74 | 75 | .. note:: 76 | 77 | The following example assumes that the getter method for your logger is named ``getLogger()``, as shown in the 78 | previous section. This may differ for you depending on what you named your getter method. 79 | 80 | .. code-block:: java 81 | 82 | getLogger().info("String"); 83 | getLogger().debug("String"); 84 | getLogger().warn("String"); 85 | getLogger().error("String"); 86 | 87 | The String is the message you wish to emit. For example: 88 | 89 | .. code-block:: java 90 | 91 | getLogger().warn("This is a warning!"); 92 | 93 | -------------------------------------------------------------------------------- /source/ore/routes/list-versions.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | List Project Versions 3 | ===================== 4 | 5 | **GET /api/v1/projects/:pluginId/versions** 6 | 7 | Returns a list of versions for a project of a given plugin ID based on given criteria. 8 | 9 | **Query parameters:** 10 | 11 | +----------+-----------------------------+-------------------------------------------------------------+ 12 | | Name | Data Type | Description | 13 | +==========+=============================+=============================================================+ 14 | | channels | Comma Separated String List | Filters versions by channels (inclusive). | 15 | +----------+-----------------------------+-------------------------------------------------------------+ 16 | | limit | Integer | Limits the number of versions returned (max / default: 10). | 17 | +----------+-----------------------------+-------------------------------------------------------------+ 18 | | offset | Integer | Drops the first *n* versions from the result list. | 19 | +----------+-----------------------------+-------------------------------------------------------------+ 20 | 21 | **Example output:** 22 | 23 | .. code-block:: json 24 | 25 | [{ 26 | "id": 1226, 27 | "createdAt": "2018-02-08 18:41:36.917", 28 | "name": "1.1", 29 | "dependencies": [{ 30 | "pluginId": "spongeapi", 31 | "version": "7.1.0" 32 | }], 33 | "pluginId": "auction", 34 | "channel": { 35 | "name": "Release", 36 | "color": "#009600" 37 | }, 38 | "fileSize": 11441, 39 | "md5": "d169809b0eda0e5d49bc60d5f69f097b", 40 | "staffApproved": false, 41 | "href": "/ewoutvs_/Auction/versions/1.1", 42 | "tags": [{ 43 | "id": 13, 44 | "name": "Sponge", 45 | "data": "7.1.0", 46 | "backgroundColor": "#F7Cf0D", 47 | "foregroundColor": "#000000" 48 | }], 49 | "downloads": 25, 50 | "author": "ewoutvs_" 51 | }, 52 | { 53 | "id": 1139, 54 | "createdAt": "2018-01-23 11:08:55.798", 55 | "name": "1.0", 56 | "dependencies": [{ 57 | "pluginId": "spongeapi", 58 | "version": "7.1.0" 59 | }], 60 | "pluginId": "auction", 61 | "channel": { 62 | "name": "Release", 63 | "color": "#009600" 64 | }, 65 | "fileSize": 11266, 66 | "md5": "2d9896413912a0ba719a9fb624b9ff8e", 67 | "staffApproved": false, 68 | "href": "/ewoutvs_/Auction/versions/1.0", 69 | "tags": [{ 70 | "id": 13, 71 | "name": "Sponge", 72 | "data": "7.1.0", 73 | "backgroundColor": "#F7Cf0D", 74 | "foregroundColor": "#000000" 75 | }], 76 | "downloads": 27 77 | }] 78 | -------------------------------------------------------------------------------- /source/plugin/commands/rawcommand.rst: -------------------------------------------------------------------------------- 1 | =========== 2 | Raw Command 3 | =========== 4 | 5 | 6 | .. javadoc-import:: 7 | org.spongepowered.api.event.lifecycle.RegisterCommandEvent 8 | org.spongepowered.api.command.Command.Raw 9 | org.spongepowered.api.command.Command 10 | org.spongepowered.plugin.PluginContainer 11 | java.lang.String 12 | 13 | 14 | The raw command interface can be used to define commands. The interface can be used as a base for custom command APIs. 15 | 16 | It is recommended to use the :doc:`commandbuilding` for simple command definitions. 17 | 18 | Writing a Command 19 | ~~~~~~~~~~~~~~~~~ 20 | 21 | The first step is to create a class for the command. The class has to implement the interface ``Command.Raw``: 22 | 23 | .. code-block:: java 24 | 25 | public class MyBroadcastCommand implements Command.Raw { 26 | 27 | private final Component usage = Component.text(""); 28 | private final Component description = Component.text("Display a message to all players"); 29 | 30 | @Override 31 | public CommandResult process(CommandCause cause, ArgumentReader.Mutable arguments) throws CommandException { 32 | String message = arguments.remaining(); 33 | Sponge.server().broadcastAudience().sendMessage(Component.text(message)); 34 | return CommandResult.success(); 35 | } 36 | 37 | @Override 38 | public List complete(CommandCause cause, ArgumentReader.Mutable arguments) throws CommandException { 39 | return Collections.emptyList(); 40 | } 41 | 42 | @Override 43 | public boolean canExecute(CommandCause cause) { 44 | return cause.hasPermission("myplugin.broadcast"); 45 | } 46 | 47 | @Override 48 | public Optional shortDescription(CommandCause cause) { 49 | return Optional.of(this.description); 50 | } 51 | 52 | @Override 53 | public Optional extendedDescription(CommandCause cause) { 54 | return Optional.empty(); 55 | } 56 | 57 | @Override 58 | public Component usage(CommandCause cause) { 59 | return this.usage; 60 | } 61 | } 62 | 63 | .. tip:: 64 | 65 | See the JavaDoc for :javadoc:`Raw` for the purposes of each method in the example 66 | 67 | Registering the Command 68 | ~~~~~~~~~~~~~~~~~~~~~~~ 69 | 70 | Now we can register the class in the :javadoc:`RegisterCommandEvent` event. You can register the command using the 71 | :javadoc:`RegisterCommandEvent#register(PluginContainer, Command, String, String...)` passing your plugin's container, 72 | an instance of the raw command and the main command as well as any aliases. 73 | 74 | .. code-block:: java 75 | 76 | @Inject 77 | PluginContainer container; 78 | 79 | @Listener 80 | public void onRegisterRawCommands(final RegisterCommandEvent event){ 81 | event.register(this.container, new MyBroadcastCommand(), "broadcast"); 82 | } 83 | -------------------------------------------------------------------------------- /source/plugin/services.rst: -------------------------------------------------------------------------------- 1 | ======== 2 | Services 3 | ======== 4 | 5 | .. javadoc-import:: 6 | java.util.function.Supplier 7 | org.spongepowered.api.Game 8 | org.spongepowered.api.Server 9 | org.spongepowered.api.event.lifecycle.ProvideServiceEvent 10 | org.spongepowered.api.service.ServiceProvider 11 | org.spongepowered.api.service.ServiceProvider.GameScoped 12 | org.spongepowered.api.service.ServiceProvider.ServerScoped 13 | org.spongepowered.api.service.permission.PermissionService 14 | org.spongepowered.api.service.permission.Subject 15 | 16 | 17 | Services provide common server functionality that is intended to be provided by plugins so that plugins that wish to use 18 | this functionality do not need to depend on any third-party plugins. Some services, such as the 19 | :javadoc:`PermissionService`, are tightly integrated into the API itself, providing the core functionality for some of 20 | the API (for example, the ``PermissionService`` supports various methods on the :javadoc:`Subject` interface). 21 | 22 | Services themselves can be :javadoc:`Server` scoped or :javadoc:`Game` scoped. Due to the potential for servers restarting 23 | multiple times within a game instance, server scoped services should at least change instance across restarts, and may 24 | be provided by different plugins. 25 | 26 | .. note:: 27 | In previous versions of SpongeAPI, plugins could register their own arbitary services to arbitary interfaces. This 28 | is no longer possible using the Sponge service provider in SpongeAPI 8 and later. 29 | 30 | Obtaining a Service 31 | =================== 32 | 33 | Services can be retrieved from the :javadoc:`ServiceProvider` via the ``serviceProvider`` method on either 34 | ``Game`` or ``Server``. Inspect :javadoc:`ServiceProvider.GameScoped` and 35 | :javadoc:`ServiceProvider.ServerScoped` for details of what services are provided in these scopes. 36 | 37 | Providing a Service 38 | =================== 39 | 40 | Service implementations are provided during the generic :javadoc:`ProvideServiceEvent`. For example, to supply a 41 | ``PermissionService``, you would listen to the event like so (swapping out the "new" call for your service 42 | construction code): 43 | 44 | .. code-block:: java 45 | 46 | import org.spongepowered.api.event.Listener 47 | import org.spongepowered.api.event.lifecycle.ProvideServiceEvent 48 | import org.spongepowered.api.service.permission.PermissionService 49 | 50 | @Listener 51 | public void providePermissionService(final ProvideServiceEvent.EngineScoped event) { 52 | event.suggest(() -> new ConcretePermissionService()); 53 | } 54 | 55 | It is important to note that it is possible that your listener will never get called. It is left up to the 56 | API implementation to decide which plugin to pick to provide a given service. With this in mind, it is highly 57 | recommended that you do not construct your service implementation yourself, instead doing so within the 58 | :javadoc:`Supplier` supplied to the ``suggest`` method. 59 | -------------------------------------------------------------------------------- /source/plugin/economy/using.rst: -------------------------------------------------------------------------------- 1 | ===================== 2 | Using the Economy API 3 | ===================== 4 | 5 | .. javadoc-import:: 6 | org.spongepowered.api.service.economy.EconomyService 7 | org.spongepowered.api.service.economy.account.Account 8 | org.spongepowered.api.service.ServiceManager 9 | org.spongepowered.api.event.service.ChangeServiceProviderEvent 10 | 11 | The Economy API unifies all economy plugins under one API. This means any plugin using the Economy API 12 | will be compatible with all economy plugins that implement said API. This page guides you through the steps of using 13 | the Economy API in your own plugin. 14 | 15 | Loading the EconomyService 16 | ========================== 17 | 18 | In order to utilize the Economy API, you must first load the :javadoc:`EconomyService` class using the :javadoc:`ServiceManager`. 19 | 20 | .. warning:: 21 | Please note that you need to pay attention to different ``game states`` while the server is starting, stopping or 22 | running when using services like the Economy API. Take a look at the :doc:`/plugin/services` page for further 23 | information. 24 | 25 | 26 | 27 | Example: Loading the EconomyService 28 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 29 | 30 | .. code-block:: java 31 | 32 | import org.spongepowered.api.service.economy.EconomyService; 33 | import org.spongepowered.api.Sponge; 34 | 35 | Optional serviceOpt = Sponge.server().serviceProvider().economyService(); 36 | if (!serviceOpt.isPresent()) { 37 |   // handle there not being an economy implementation 38 | } 39 | EconomyService economyService = serviceOpt.get(); 40 | 41 | Using the EconomyService 42 | ======================== 43 | 44 | After loading the ``EconomyService`` and assigning it to a variable, you are ready to access all of the features the 45 | Economy API has to offer. 46 | 47 | Example: Getting a player's balance 48 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 49 | 50 | .. code-block:: java 51 | 52 | import org.spongepowered.api.entity.living.player.Player; 53 | import org.spongepowered.api.service.economy.EconomyService; 54 | import org.spongepowered.api.service.economy.account.UniqueAccount; 55 | import java.math.BigDecimal; 56 | import java.util.Optional; 57 | 58 | Optional uOpt = economyService.findOrCreateAccount(player.getUniqueId()); 59 | if (uOpt.isPresent()) { 60 | UniqueAccount acc = uOpt.get(); 61 | BigDecimal balance = acc.balance(economyService.defaultCurrency()); 62 | } 63 | 64 | Some :javadoc:`Account` methods require variables such as: 65 | 66 | * Currency: The currency involved in the exchange 67 | * Cause: What caused the change to the account 68 | * Context: The context that the change occurred in 69 | 70 | These are for more advanced uses, but still must be filled in. Below is a list of acceptable default values: 71 | 72 | * Currency: :javadoc:`EconomyService#defaultCurrency()` 73 | * Cause: ``Cause.of(EventContext.builder().add(EventContextKeys.PLUGIN, plugin).build(), plugin)`` 74 | * Context: ``new HashSet()`` 75 | -------------------------------------------------------------------------------- /source/plugin/economy/basics.rst: -------------------------------------------------------------------------------- 1 | ============== 2 | Basic Concepts 3 | ============== 4 | 5 | .. javadoc-import:: 6 | org.spongepowered.api.event.economy.EconomyTransactionEvent 7 | org.spongepowered.api.service.economy.Currency 8 | org.spongepowered.api.service.economy.EconomyService 9 | org.spongepowered.api.service.economy.account.Account 10 | org.spongepowered.api.service.economy.transaction.ResultType 11 | org.spongepowered.api.service.economy.transaction.TransactionResult 12 | 13 | The Sponge Economy API has a few basic components that developers should be familiar with: 14 | 15 | * EconomyService 16 | * Currency 17 | * Accounts 18 | * Transactions 19 | 20 | The EconomyService 21 | ================== 22 | 23 | The :javadoc:`EconomyService` is the basis of the Economy API. It is used to interact via the Economy API, stores an 24 | economy's currencies and provides methods for account management. 25 | 26 | .. warning:: 27 | 28 | Sponge does not provide a default implementation for the ``EconomyService``. It's completely up to plugins to 29 | implement the Economy API. This means that you have to rely on another plugin which implements the service or you'll 30 | have to implement it yourself, if you want to make use of it. 31 | 32 | Currency 33 | ======== 34 | 35 | The :javadoc:`Currency` object represents a form of Currency. ``Currency`` stores a display name (plural and singular), 36 | a symbol, the number of fractional digits, and whether the currency is the default currency for the economy. If the 37 | economy plugin chooses, it can support multiple currencies. 38 | 39 | Accounts 40 | ======== 41 | 42 | :javadoc:`Account`\ s are used to store economy information about a specific player or other object (i.e. bank, 43 | business, entity). There are two account types in the Sponge Economy API: 44 | 45 | Virtual Accounts 46 | ~~~~~~~~~~~~~~~~ 47 | 48 | Virtual accounts are tied to an identifier, which is stored as a string. Virtual accounts can be tied to almost 49 | anything, but are commonly used for things such as banks, or non-players. To get the id of a virtual account, use 50 | ``identifier()``. 51 | 52 | Unique Accounts 53 | ~~~~~~~~~~~~~~~ 54 | 55 | Unique accounts are tied to a UUID, usually a player. To get the UUID of an unique account, use ``uniqueId()``. 56 | 57 | Transactions 58 | ============ 59 | 60 | Transactions represent an account's change in balance. There are currently three types of transactions: 61 | 62 | - Deposit: Occurs when an account has funds added to it 63 | - Withdraw: Occurs when an account has funds removed from it 64 | - Transfer: Occurs when an account exchanges funds with another account 65 | 66 | When a transfer occurs, the :javadoc:`EconomyTransactionEvent` is fired. Using this event, you can get the 67 | :javadoc:`TransactionResult`. The ``TransactionResult`` stores data about the transaction that occurred, including: 68 | 69 | - Account involved 70 | - Currency involved 71 | - Amount of currency involved 72 | - Transaction type 73 | - Result of the transaction 74 | 75 | You can view all possible transaction results on the :javadoc:`ResultType` JavaDocs page. 76 | -------------------------------------------------------------------------------- /source/plugin/practices/bad.rst: -------------------------------------------------------------------------------- 1 | ============= 2 | Bad Practices 3 | ============= 4 | 5 | .. javadoc-import:: 6 | org.spongepowered.api.block.tileentity.TileEntity 7 | org.spongepowered.api.command.CommandSource 8 | org.spongepowered.api.data.DataHolder 9 | org.spongepowered.api.entity.Entity 10 | org.spongepowered.api.entity.living.player.Player 11 | org.spongepowered.api.entity.living.player.User 12 | org.spongepowered.api.service.permission.Subject 13 | org.spongepowered.api.world.Chunk 14 | org.spongepowered.api.world.Dimension 15 | org.spongepowered.api.world.World 16 | 17 | These bad practices should be avoided, as they can lead to memory leaks (``OutOfMemoryError``), lag or 18 | inconsistencies. 19 | 20 | 21 | Storing References 22 | ================== 23 | 24 | Some instances such as 25 | 26 | * :javadoc:`DataHolder` 27 | * :javadoc:`TileEntity` 28 | * :javadoc:`CommandSource` 29 | * :javadoc:`Entity` 30 | * :javadoc:`Player` 31 | * :javadoc:`Subject` 32 | * :javadoc:`Chunk` 33 | * :javadoc:`Dimension` 34 | * :javadoc:`World` 35 | * :javadoc:`User` 36 | * and containers that **MIGHT** contain any of the above elements, including 37 | * ``Collections`` 38 | * ``Maps`` 39 | 40 | should **NEVER** be stored or cached in plugins. 41 | 42 | These are the main reasons for this: 43 | 44 | * The references prevent proper garbage collection 45 | * The instances might no longer be valid 46 | 47 | This can easily be avoided by using the corresponding snapshots or saving the UUID of the given instances and requesting 48 | a live instance when you need it. 49 | 50 | 51 | IO on the main thread 52 | ===================== 53 | 54 | Executing some IO operations such as loading a config/data file or checking for updates/connecting to a website takes 55 | much time and greatly affects the TPS on the server. Such tasks should be done either in their own threads, or using the 56 | inbuilt scheduler's async feature. However, it is perfectly fine to load required files/config on the main thread during 57 | server startup/plugin initialization. 58 | 59 | .. code-block:: java 60 | 61 | Sponge.asyncScheduler().submit(Task.builder().execute(this::checkForUpdates).build()); 62 | 63 | For more details refer to the :doc:`scheduler <../scheduler>` docs. 64 | 65 | If this is done incorrectly, you may see clients time out, or the watchdog may even kill the server. 66 | 67 | 68 | Accessing game objects outside the main thread 69 | ============================================== 70 | 71 | Accessing game objects outside of the main thread can lead to crashes, inconsistencies and various other problems and 72 | should be avoided. If you have a lengthy operation on a different thread use the :doc:`scheduler <../scheduler>` to make 73 | changes to such game objects on the main thread. If you want to use a game object in a different thread use a snapshot 74 | of the instance or a detached data container. 75 | 76 | .. warning:: 77 | 78 | If this is done wrong, you can get a ``ConcurrentModificationException`` with or without a server crash at best and 79 | a corrupted player/world/server at worst. 80 | -------------------------------------------------------------------------------- /source/plugin/database.rst: -------------------------------------------------------------------------------- 1 | ========= 2 | Databases 3 | ========= 4 | 5 | .. warning:: 6 | These docs were written for SpongeAPI 7 and are likely out of date. 7 | `If you feel like you can help update them, please submit a PR! `__ 8 | 9 | .. javadoc-import:: 10 | java.lang.String 11 | org.spongepowered.api.service.sql.SqlService 12 | 13 | SQL 14 | --- 15 | Sponge provides a convenient abstraction for establishing JDBC database connections that handles the complexities of 16 | establishing an efficient pooled connection from a JDBC URL. 17 | 18 | While the SQL service supports any JDBC connector, the Forge implementation of Sponge only ships with the most common: 19 | 20 | - MySQL 21 | - Sqlite 22 | - H2 23 | 24 | .. warning:: 25 | Because Sqlite has many limitations, its usage is strongly discouraged except in cases where legacy compatibility 26 | is required. H2 is our recommended file-backed database implementation. 27 | 28 | Usage 29 | ~~~~~ 30 | 31 | A data source can be accessed through the plugin's service manager: 32 | 33 | .. code-block:: java 34 | 35 | import org.spongepowered.api.Sponge; 36 | import org.spongepowered.api.service.sql.SqlService; 37 | 38 | import java.sql.Connection; 39 | import java.sql.PreparedStatement; 40 | import java.sql.ResultSet; 41 | import java.sql.SQLException; 42 | import javax.sql.DataSource; 43 | 44 | private SqlService sql; 45 | public DataSource getDataSource(String jdbcUrl) throws SQLException { 46 | if (sql == null) { 47 | sql = Sponge.getServiceManager().provide(SqlService.class).get(); 48 | } 49 | return sql.getDataSource(jdbcUrl); 50 | } 51 | 52 | // Later on 53 | public void myMethodThatQueries() throws SQLException { 54 | String uri = "jdbc:h2:imalittledatabaseshortandstout.db"; 55 | String sql = "SELECT * FROM test_tbl"; 56 | 57 | try (Connection conn = getDataSource(uri).getConnection(); 58 | PreparedStatement stmt = conn.prepareStatement(sql); 59 | ResultSet results = stmt.executeQuery()) { 60 | 61 | while (results.next()) { 62 | // ... 63 | } 64 | 65 | } 66 | 67 | } 68 | 69 | JDBC URLs should be obtained from :javadoc:`SqlService#getConnectionUrlFromAlias(String)`, with an alias that 70 | matches one of the JDBC URL aliases listed in Sponge's global configuration (``config/sponge/global.conf``) 71 | under the ``sponge.sql.aliases`` key. 72 | 73 | The SQL service provides a pooled connection, so getting a connection from the returned ``DataSource`` 74 | is not expensive. Therefore, we recommended not keeping connections around, and closing them soon after use as shown 75 | above. Any ``PreparedStatement`` and ``ResultSet`` created should also be closed after use, with ``object.close()`` 76 | or, preferably, through a try-with-resources block. 77 | 78 | NoSQL 79 | ----- 80 | Sponge does not currently provide any special abstraction over NoSQL databases (MongoDB etc.). Plugins that wish to use 81 | NoSQL databases must provide their own connectors. 82 | -------------------------------------------------------------------------------- /tools/code-checker/src/test/java/org/spongepowered/docs/tools/codeblock/KeywordRedirectingPredicateTest.java: -------------------------------------------------------------------------------- 1 | /* 2 | * This file is part of SpongeAPI, licensed under the MIT License (MIT). 3 | * 4 | * Copyright (c) SpongePowered 5 | * Copyright (c) contributors 6 | * 7 | * Permission is hereby granted, free of charge, to any person obtaining a copy 8 | * of this software and associated documentation files (the "Software"), to deal 9 | * in the Software without restriction, including without limitation the rights 10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 | * copies of the Software, and to permit persons to whom the Software is 12 | * furnished to do so, subject to the following conditions: 13 | * 14 | * The above copyright notice and this permission notice shall be included in 15 | * all copies or substantial portions of the Software. 16 | * 17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 | * THE SOFTWARE. 24 | */ 25 | package org.spongepowered.docs.tools.codeblock; 26 | 27 | import static org.junit.jupiter.api.Assertions.assertEquals; 28 | 29 | import java.util.ArrayList; 30 | import java.util.Arrays; 31 | import java.util.List; 32 | import java.util.stream.Collectors; 33 | import java.util.stream.Stream; 34 | 35 | import org.junit.jupiter.api.Test; 36 | 37 | class KeywordRedirectingPredicateTest { 38 | 39 | @Test 40 | void test() { 41 | List drain = new ArrayList<>(); 42 | assertEquals(Arrays.asList("Foo", "Bar", "ON", "OFF", "was"), 43 | Stream.of("Foo", "Bar", "ON", "Fire", "OFF", "was", "destroyed") 44 | .filter(new KeywordRedirectingPredicate<>(s -> s.length() > 3, drain::add)) 45 | .collect(Collectors.toList())); 46 | assertEquals(Arrays.asList("Fire", "destroyed"), drain); 47 | 48 | drain.clear(); 49 | 50 | assertEquals(Arrays.asList("Foo", "Bar", "OFF", "Fire", "OFF", "was"), 51 | Stream.of("Foo", "Bar", "OFF", "Fire", "OFF", "was", "destroyed") 52 | .filter(new KeywordRedirectingPredicate<>(s -> s.length() > 4, drain::add)) 53 | .collect(Collectors.toList())); 54 | assertEquals(Arrays.asList("destroyed"), drain); 55 | 56 | drain.clear(); 57 | 58 | assertEquals(Arrays.asList(), 59 | Stream.of("Foo", "Bar", "ON", "Fire", "ON", "was", "destroyed") 60 | .filter(new KeywordRedirectingPredicate<>(s -> s.length() >= 2, drain::add)) 61 | .collect(Collectors.toList())); 62 | assertEquals(Arrays.asList("Foo", "Bar", "ON", "Fire", "ON", "was", "destroyed"), drain); 63 | } 64 | 65 | } 66 | -------------------------------------------------------------------------------- /source/contributing/index.rst: -------------------------------------------------------------------------------- 1 | ====================== 2 | Contributing to Sponge 3 | ====================== 4 | 5 | This section shows you how to get involved with Sponge. 6 | 7 | What are the projects I can help with? 8 | ====================================== 9 | 10 | The Sponge Project and its parts are maintained on `GitHub `_. If you're unfamiliar 11 | with GitHub and the tool git, then take a look at :doc:`howtogit` first. A read of our :doc:`guidelines` is strongly 12 | advised before starting any work. There are several projects we're currently maintaining: 13 | 14 | * SpongeAPI 15 | * SpongeForge 16 | * SpongeVanilla 17 | * SpongeCommon 18 | * Mixin 19 | * SpongeDocs 20 | * Ore 21 | 22 | If you want to know more about the structure of the project and how everything is tied together, head over to 23 | :doc:`/about/structure`. 24 | 25 | What kind of help is needed? 26 | ============================ 27 | 28 | Basic contributions 29 | ~~~~~~~~~~~~~~~~~~~ 30 | 31 | This can be done by almost everyone. You don't need to know a programming language like Java or Python to: 32 | 33 | * test SpongeForge or SpongeVanilla and report bugs or usage quirks 34 | * report or suggest any errors, faults or bugs you encounter 35 | * post suggestions or idea you have which would make Sponge better 36 | 37 | Reporting bugs best via our `GitHub repositories `_, suggestions fit onto our 38 | `forums `_. Just have a look at our 39 | :doc:`Bug Reporting page ` for further instructions. 40 | 41 | Intermediate Contributions 42 | ~~~~~~~~~~~~~~~~~~~~~~~~~~ 43 | 44 | You should at least have basic knowledge of Java, Python or reST to help out on the following tasks: 45 | 46 | * help fixing bugs 47 | * finish the implementation of the API (SpongeForge and SpongeVanilla) 48 | * :doc:`help writing the SpongeDocs ` 49 | * help `translate the Docs on Crowdin `_ 50 | * help out developing Ore 51 | 52 | The development of the `SpongeAPI `_, 53 | `SpongeForge `_, 54 | `SpongeVanilla `_ and `Ore `_ as 55 | well as the `SpongeDocs `_ is done in several repositories hosted on GitHub. 56 | 57 | Advanced Contributions 58 | ~~~~~~~~~~~~~~~~~~~~~~ 59 | 60 | And finally, these are the most difficult things you can help out with. Advanced knowledge of Java, Minecraft and at 61 | least basic knowledge of the `SpongeAPI `_ and its 62 | `structure `_ is strongly advised before attempting to help out with: 63 | 64 | * adding functionality to the API (:doc:`implementation/pr`) 65 | * implementing advanced API functionality in the implementations 66 | 67 | Contents 68 | ======== 69 | 70 | .. toctree:: 71 | :maxdepth: 2 72 | :titlesonly: 73 | 74 | guidelines 75 | howtogit 76 | implementation/index 77 | spongedocs 78 | porting 79 | versioning 80 | -------------------------------------------------------------------------------- /source/server/getting-started/launch-script.rst: -------------------------------------------------------------------------------- 1 | ======================== 2 | Creating a Launch Script 3 | ======================== 4 | 5 | .. note:: 6 | 7 | These instructions apply only if you plan to run your Minecraft server on your own machine. Most shared Minecraft 8 | hosts will create a launch script for you. 9 | 10 | Writing a Launch Script 11 | ======================= 12 | 13 | First, open a text editor such as Atom, Sublime Text, or Notepad. Write (or paste) a launch script for your server. 14 | Examples of simple launch scripts for Windows, macOS, and Linux have been provided below. Keep the RAM limitations 15 | of your machine in mind. 16 | 17 | .. note:: 18 | 19 | The following examples are generic. For a Forge server using Sponge (coremod), change ``forge-1.12.2-XYZ-universal.jar`` 20 | to whatever your Forge version in the server directory is named. To launch a SpongeVanilla server, change 21 | ``forge-1.12.2-XYZ-universal.jar`` to the name of the SpongeVanilla.jar file. 22 | 23 | Windows 24 | ~~~~~~~ 25 | 26 | .. code-block:: bat 27 | 28 | java -Xms1G -Xmx2G -jar forge-1.12.2-XYZ-universal.jar 29 | pause 30 | 31 | Save your Windows launch script as ``launch.bat``. 32 | 33 | .. warning:: 34 | Launching your server in a Command Prompt or PowerShell environment can lead to the server hanging due to the 35 | ``Quick Edit Mode`` of these shells. This mode freezes the process when you highlight something or click inside the 36 | console window. During this time, messages captured in the log will state that the server skipped many seconds or 37 | minutes worth of ticks. You can prevent this from occurring by not highlighting any text on the screen and not 38 | clicking inside the window, or by disabling the ``Quick Edit Mode`` in the Properties dialogue. 39 | 40 | macOS 41 | ~~~~~ 42 | 43 | .. code-block:: bash 44 | 45 | #!/bin/bash 46 | cd "$(dirname "$0")" 47 | java -Xms1G -Xmx2G -jar forge-1.12.2-XYZ-universal.jar 48 | 49 | Save your Mac launch script as ``launch.command``. 50 | 51 | Linux 52 | ~~~~~ 53 | 54 | .. code-block:: sh 55 | 56 | #!/bin/sh 57 | cd "$(dirname "$(readlink -fn "$0")")" 58 | java -Xms1G -Xmx2G -jar forge-1.12.2-XYZ-universal.jar 59 | 60 | Save your Linux launch script as ``launch.sh``. 61 | 62 | Running a Launch Script 63 | ======================= 64 | 65 | Ensure you are running your launch script out of a folder created especially for your server. This is for your own 66 | sanity; unfortunately, Spongie is unable to soak up your tears if you do not do this. 67 | 68 | You may run your launch script by double-clicking it. If you are using a console or terminal, navigate to the directory 69 | of the script and run it. Keep in mind that you must agree to the Mojang EULA in order to run a server. 70 | 71 | .. note:: 72 | 73 | The default Minecraft server GUI console is disabled by Sponge, because it is very processor-intensive. 74 | 75 | .. warning:: 76 | 77 | If you get a permissions error when attempting to launch your server on a Mac, try this: 78 | 79 | * Open the Terminal. 80 | * Type ``chmod a+x``, with a space at the end. 81 | * Drag your launch script to the Terminal. 82 | * Press enter. 83 | -------------------------------------------------------------------------------- /source/contributing/guidelines.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | Contribution Guidelines 3 | ======================= 4 | 5 | There will always be a need for developers to help us improve SpongeAPI. There is no such thing as a perfect project and 6 | things can always be improved. If you are a developer and are interested in helping then please do not hesitate. Just 7 | make sure you follow our guidelines. 8 | 9 | .. note:: 10 | Developers who show determination and consistency in their contributions to the project may be invited to join the 11 | Sponge Staff by Team Leaders, at their discretion. There is no formal application process. 12 | Please don't ask to be staff, we'll ask you. 13 | 14 | General steps 15 | ============= 16 | 17 | 1. Setup your workspace as described in :doc:`/preparing/index`. 18 | 19 | #. Make sure you're familiar with Git and GitHub. If your knowledge needs a refresh, take a look here: :doc:`howtogit` 20 | 21 | #. Check for existing issues in the `SpongeAPI `_, 22 | `SpongeCommon `_ and 23 | `SpongeDocs `_ repositories. There is possibly someone else already 24 | working on the same thing. You can also check 25 | `issues marked with "help wanted" `_ for existing 26 | issues we need your help with. 27 | 28 | .. note:: 29 | Please don't submit pull requests for small, non-functional changes such as fixing typos or renaming variable names. 30 | Instead, you can: 31 | 32 | * `join #spongedev on IRC (irc.esper.net) `_ 33 | and we'll change it together with the other smaller changes. 34 | 35 | * Join our `Discord Server `_ and post on the ``#dev`` channel. 36 | Discord and IRC are linked, so don't worry. We won't miss your message! 37 | 38 | * You can also add it to our list of 39 | `Minor Issues on GitHub `_. 40 | 41 | 4. If the issue requires a bigger change you may want to submit the issues without the necessary changes first, so we 42 | can confirm the issue and know that you're working on fixing it. You should also create a draft pull 43 | request or comment with ``~wip`` so we can already start reviewing them. 44 | 45 | #. Fork the project, clone it and make your changes in an extra branch. 46 | 47 | #. Test your changes (make sure it compiles!), commit and push them to your fork. 48 | 49 | #. Submit the pull request with a short summary what you've changed and why it should be changed in that way. 50 | 51 | #. If you make additional changes, push new commits to your branch. **Do not squash your changes**, that makes it 52 | extremely hard to see what you've changed compared to the previous version of your pull request. 53 | 54 | #. Make sure your PR is rebased to the latest changes of the branch you're intending to merge it into. If you need help 55 | rebasing it, just ask! 56 | 57 | .. tip:: 58 | If you're unsure which branch you should base your work on, read about our :doc:`versioning` before submitting your PR. 59 | -------------------------------------------------------------------------------- /source/plugin/entities/spawning.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | Spawning an Entity 3 | ================== 4 | 5 | .. warning:: 6 | These docs were written for SpongeAPI 7 and are likely out of date. 7 | `If you feel like you can help update them, please submit a PR! `__ 8 | 9 | .. javadoc-import:: 10 | com.flowpowered.math.vector.Vector3d 11 | org.spongepowered.api.entity.Entity 12 | org.spongepowered.api.entity.EntityType 13 | org.spongepowered.api.event.cause.entity.spawn.SpawnType 14 | org.spongepowered.api.event.cause.entity.spawn.SpawnTypes 15 | org.spongepowered.api.world.Location 16 | org.spongepowered.api.world.extent.Extent 17 | org.spongepowered.api.world.extent.EntityUniverse 18 | 19 | You will need three things for spawning an :javadoc:`Entity`: a :javadoc:`Location`, an :javadoc:`Extent`, and an 20 | :javadoc:`EntityType`. The process for getting these is quite simple, you just need to grab a ``Location`` from 21 | somewhere in your plugin code and choose the type of ``Entity`` you wish to spawn. 22 | 23 | For example, let's try to spawn a Creeper: 24 | 25 | .. code-block:: java 26 | 27 | import org.spongepowered.api.entity.Entity; 28 | import org.spongepowered.api.entity.EntityTypes; 29 | import org.spongepowered.api.event.CauseStackManager.StackFrame; 30 | import org.spongepowered.api.event.cause.entity.spawn.SpawnTypes; 31 | import org.spongepowered.api.world.Location; 32 | import org.spongepowered.api.world.World; 33 | 34 | import java.util.Optional; 35 | 36 | public void spawnEntity(Location spawnLocation) { 37 | World world = spawnLocation.getExtent(); 38 | 39 | Entity creeper = world.createEntity(EntityTypes.CREEPER, spawnLocation.getPosition()); 40 | 41 | // We need to push a new cause StackFrame to the stack so we can add our own causes 42 | // In previous versions of the API you had to submit a Cause parameter 43 | // that would often not contain the real root cause 44 | // By default the current plugin's PluginContainer is already pushed to the stack. 45 | try (StackFrame frame = Sponge.getCauseStackManager().pushCauseFrame()) { 46 | frame.addContext(EventContextKeys.SPAWN_TYPE, SpawnTypes.PLUGIN); 47 | world.spawnEntity(creeper); 48 | } 49 | } 50 | 51 | This will grab the world from our ``Location``, which we will need for the actual spawning. Next, it uses 52 | :javadoc:`EntityUniverse#createEntity(EntityType, Vector3d)` to create the entity, but do note that this does not 53 | spawn the entity into the world, it just will create it. We will need to specify the type of ``Entity`` to spawn, and 54 | the co-ordinates from our ``Location``. 55 | 56 | Once we have created our ``Entity`` we can then use the world for spawning the ``Entity``. We should specify a 57 | ``Cause`` for the spawning so other plugins can handle it accordingly. For spawning ``Entity``\ s, it is best to use a 58 | :javadoc:`SpawnType` as part of the context. In this example, we stated that our entity was spawned from a plugin, 59 | however we can make it any cause/context that best describes why we are spawning this in, such as a mob spawner 60 | (See :javadoc:`SpawnTypes#MOB_SPAWNER`), or spawn egg (See :javadoc:`SpawnTypes#SPAWN_EGG`). 61 | -------------------------------------------------------------------------------- /source/plugin/project/gradle.rst: -------------------------------------------------------------------------------- 1 | ================= 2 | Setting Up Gradle 3 | ================= 4 | 5 | .. _using-spongegradle: 6 | 7 | Using SpongeGradle 8 | ================== 9 | 10 | Using SpongeGradle_ is very simple and allows you to minimize the necessary Gradle configuration for setting up a 11 | Sponge plugin on Gradle. Additionally, it provides integration for :doc:`/plugin/plugin-meta`, such as automatically 12 | contributing the group, project name, version and description defined in your build script to the built plugin, so you 13 | only need to update your plugin version in one file. 14 | 15 | .. tip:: 16 | Most problems are caused by attempting to use an outdated Gradle version. We recommend using the latest Gradle 17 | version together with SpongeGradle_. :ref:`The Gradle section of the build systems page ` explains how 18 | to setup Gradle on your computer. 19 | 20 | Below is a simple template that should be usable for most plugins. **Make sure to replace the group with the group ID 21 | you have chosen before.** 22 | 23 | .. code-block:: groovy 24 | 25 | plugins { 26 | id 'java-library' 27 | id("org.spongepowered.plugin") version '0.11.3' 28 | } 29 | 30 | // This may not be required, but has solved issues in the past 31 | compileJava.options.encoding = 'UTF-8' 32 | 33 | // TODO: Change the following to match your information 34 | group = 'com.example' 35 | version = '1.0.0-SNAPSHOT' 36 | description = 'Here lies an example plugin definition' 37 | 38 | repositories { 39 | mavenCentral() 40 | } 41 | 42 | sponge { 43 | apiVersion("8.1.0") 44 | licence("MIT") 45 | loader { 46 | name(PluginLoaders.JAVA_PLAIN) 47 | version("1.0") 48 | } 49 | plugin("**plugin Id**") { 50 | displayName("**Plugin Name**") 51 | entrypoint("**Plugin Entrypoint**") 52 | description("**Plugin Description**") 53 | dependency("spongeapi") { 54 | loadOrder(PluginDependency.LoadOrder.AFTER) 55 | optional(false) 56 | } 57 | } 58 | } 59 | 60 | These few lines handle most settings you would normally do manually: 61 | 62 | * Basic Gradle Java setup 63 | * Add Sponge's Maven repository (and Maven Central) 64 | * Set up a plugin with the project name in lower case as **plugin ID** 65 | * Automatically includes the project name, description and :doc:`version <../project/version-numbers>` in 66 | :doc:`/plugin/plugin-meta`. 67 | 68 | Without SpongeGradle 69 | ==================== 70 | 71 | .. warning:: 72 | We recommend using :ref:`SpongeGradle ` for Gradle plugins since it will provide additional Gradle 73 | integration for Sponge plugins. 74 | 75 | Generally, everything necessary to compile a Sponge plugin using Gradle can be done by simply adding the SpongeAPI 76 | dependency to your project: 77 | 78 | .. code-block:: groovy 79 | 80 | repositories { 81 | mavenCentral() 82 | maven { 83 | name = 'sponge-repo' 84 | url = 'https://repo.spongepowered.org/repository/maven-public/' 85 | } 86 | } 87 | 88 | dependencies { 89 | compile 'org.spongepowered:spongeapi:8.0.0' 90 | } 91 | 92 | .. _SpongeGradle: https://github.com/SpongePowered/SpongeGradle 93 | -------------------------------------------------------------------------------- /tools/code-checker/src/main/java/org/spongepowered/docs/tools/codeblock/RepeatedKeywordPredicate.java: -------------------------------------------------------------------------------- 1 | /* 2 | * This file is part of SpongeAPI, licensed under the MIT License (MIT). 3 | * 4 | * Copyright (c) SpongePowered 5 | * Copyright (c) contributors 6 | * 7 | * Permission is hereby granted, free of charge, to any person obtaining a copy 8 | * of this software and associated documentation files (the "Software"), to deal 9 | * in the Software without restriction, including without limitation the rights 10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 | * copies of the Software, and to permit persons to whom the Software is 12 | * furnished to do so, subject to the following conditions: 13 | * 14 | * The above copyright notice and this permission notice shall be included in 15 | * all copies or substantial portions of the Software. 16 | * 17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 | * THE SOFTWARE. 24 | */ 25 | package org.spongepowered.docs.tools.codeblock; 26 | 27 | import static java.util.Objects.requireNonNull; 28 | 29 | import java.util.function.Predicate; 30 | 31 | /** 32 | * Predicate that will only match if the input consecutively matches the 33 | * underlying filter at least a certain number of times. 34 | * 35 | * @param The type of data this predicate deals this. 36 | */ 37 | public class RepeatedKeywordPredicate implements Predicate { 38 | 39 | private final Predicate predicate; 40 | private final int requiredRepetitions; 41 | private int currentRepetitions = 0; 42 | 43 | /** 44 | * Creates a new RepeatedKeywordPredicate using the given predicate that 45 | * must match at least the given number of repetitions. 46 | * 47 | *

48 | * Note: The match counter is increased for the first match, so this 49 | * predicate will return true for all matching elements if 50 | * requiredRepetitions is set to 1. 51 | *

52 | * 53 | * @param predicate The filter used to check the input. 54 | * @param requiredRepetitions The required number of consecutive matches 55 | * before this predicate will pass any tests. Must be > 1. 56 | */ 57 | public RepeatedKeywordPredicate(Predicate predicate, int requiredRepetitions) { 58 | this.predicate = requireNonNull(predicate, "predicate"); 59 | if (requiredRepetitions <= 0) { 60 | throw new IllegalArgumentException("requiredRepetitions cannot be zero or less"); 61 | } 62 | this.requiredRepetitions = requiredRepetitions; 63 | } 64 | 65 | @Override 66 | public boolean test(T t) { 67 | if (this.predicate.test(t)) { 68 | this.currentRepetitions++; 69 | } else { 70 | this.currentRepetitions = 0; 71 | } 72 | return this.currentRepetitions >= this.requiredRepetitions; 73 | } 74 | 75 | } 76 | -------------------------------------------------------------------------------- /source/plugin/inventory/creating.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | Inventory Creation 3 | ================== 4 | 5 | 6 | Building free form inventories 7 | ============================== 8 | 9 | You can build inventories by either joining two inventories together using `union(inventory)` 10 | or building a new inventory from scratch or based on other inventories: 11 | 12 | .. note:: 13 | Free form inventories **cannot** be opened by a player. To show the inventory to a player a ViewableInventory is needed. 14 | 15 | .. code-block:: java 16 | 17 | // Basic indexed Inventory 18 | public static Inventory buildIndexedInventory(int capacity) { 19 | return Inventory.builder().slots(capacity).completeStructure().plugin(this.pluginContainer).build(); 20 | } 21 | 22 | // Basic grid Inventory 23 | public static Inventory buildIndexedInventory(int x, int y) { 24 | return Inventory.builder().grid(x, y).completeStructure().plugin(this.pluginContainer).build(); 25 | } 26 | 27 | // Combined inventories 28 | public static Inventory buildIndexedInventory(Inventory base, int additionalCapacity) { 29 | return Inventory.builder().inventory(base).slots(additionalCapacity).completeStructure().plugin(this.pluginContainer).build(); 30 | } 31 | 32 | // Inventory with carrier and identity 33 | public static Inventory buildIndexedInventory(int capacity) { 34 | return Inventory.builder().slots(capacity).completeStructure() 35 | .plugin(this.pluginContainer) 36 | .identity(uuid) 37 | .carrier(carrier) 38 | .build(); 39 | } 40 | 41 | Building viewable inventories 42 | ============================= 43 | 44 | To build a viewable inventory you need to follow the strict structure of a `ContainerType`. 45 | Completing the structure on en empty structure will attempt to replicate the vanilla inventory. 46 | Completing the structure on an incomplete structure will fill the rest with empty dummy slots. 47 | 48 | .. code-block:: java 49 | 50 | // Simple 3x3 inventory - looks like a Dropper 51 | public ViewableInventory simpleThreeByThree() { 52 | return ViewableInventory.builder().type(ContainerTypes.GENERIC_3X3).completeStructure().plugin(this.plugin).build(); 53 | } 54 | 55 | // To replicate vanilla behaviour of an inventory. e.g. anvil provide no structure 56 | public ViewableInventory vanillaAnvil() { 57 | return ViewableInventory.builder().type(ContainerTypes.ANVIL).completeStructure().plugin(this.plugin).build(); 58 | } 59 | 60 | // Chest 9x3 View of 3 other 3x3 inventories 61 | public ViewableInventory threeByThreeByThree() { 62 | Inventory i1 = Inventory.builder().grid(3, 3).completeStructure().plugin(this.pluginContainer).build(); 63 | Inventory i2 = Inventory.builder().grid(3, 3).completeStructure().plugin(this.pluginContainer).build(); 64 | Inventory i3 = Inventory.builder().grid(3, 3).completeStructure().plugin(this.pluginContainer).build(); 65 | return ViewableInventory.builder().type(ContainerTypes.GENERIC_9X3) 66 | .grid(i1.slots(), Vector2i.from(3, 3), Vector2i.from(0, 0)) 67 | .grid(i2.slots(), Vector2i.from(3, 3), Vector2i.from(3, 0)) 68 | .grid(i3.slots(), Vector2i.from(3, 3), Vector2i.from(6, 0)) 69 | .completeStructure().plugin(this.plugin).build(); 70 | } 71 | -------------------------------------------------------------------------------- /source/plugin/metrics.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | Metrics Collection 3 | ================== 4 | 5 | .. warning:: 6 | These docs were written for SpongeAPI 7 and are likely out of date. 7 | `If you feel like you can help update them, please submit a PR! `__ 8 | 9 | .. javadoc-import:: 10 | org.spongepowered.api.Sponge 11 | org.spongepowered.api.plugin.PluginContainer 12 | org.spongepowered.api.util.metric.MetricsConfigManager 13 | 14 | Collection of metrics from servers that use your plugin can be an incredibly useful tool for knowing what direction 15 | to take your plugin in. However, the :doc:`/ore/guidelines` (under External Connections) state that plugins may only 16 | collect metrics if informed consent has been granted. Such consent must be **opt-in**, metrics collection must be off 17 | by default. 18 | 19 | To simplify gathering consent, Sponge provides an API that allow plugins to check for this consent in a central way. 20 | 21 | Metrics collection consent is on a per-plugin basis. Plugins **must not** assume that consent for one plugin means 22 | consent for all. 23 | 24 | Obtaining Consent 25 | ================= 26 | 27 | In order to gain consent from server owners, plugins may request that server owners enable metrics. This can be 28 | of the form of a message on startup instructing the players that they can enable metrics by updating the configuration 29 | option in configuration files. SpongeForge and SpongeVanilla also provide the ``/sponge metrics enable`` 30 | command. 31 | 32 | Plugins **may** prompt server owners to run the command or allow for a "one click" enable in game. 33 | 34 | .. warning:: 35 | Plugins **may not** run the ``/sponge metrics enable`` command without a server owner's informed 36 | consent. Doing so will cause a plugin to be rejected from the Ore platform. 37 | 38 | .. note:: 39 | The ``/sponge metrics`` command is only guaranteed to exist on the ``SpongeForge`` and ``SpongeVanilla`` server 40 | implementations. Other implementations, such as ``Lantern``, may not include this command. 41 | 42 | Checking for Consent 43 | ==================== 44 | 45 | The :javadoc:`MetricsConfigManager` allows you to determine if your plugin has gained consent to send metrics. This 46 | can either be injected into your plugin class, or obtained via :javadoc:`Sponge#getMetricsConfigManager()` object 47 | on demand. 48 | 49 | **Every time** your plugin wishes to send metrics, you must check the 50 | :javadoc:`MetricsConfigManager#getCollectionState(PluginContainer)`, supplying the :javadoc:`PluginContainer` of 51 | your plugin. Metrics must only be sent if this returns ``Tristate#TRUE`` for your plugin. 52 | 53 | The following example shows how to use field injections to get the ``MetricsConfigManager`` and the 54 | ``PluginContainer`` for your plugin, and uses those to determine whether consent to send metrics has been obtained. 55 | 56 | **Example** 57 | 58 | .. code-block:: java 59 | 60 | import com.google.inject.Inject; 61 | import org.spongepowered.api.plugin.PluginContainer; 62 | import org.spongepowered.api.util.metric.MetricsConfigManager; 63 | 64 | @Inject 65 | private PluginContainer container; 66 | 67 | @Inject 68 | private MetricsConfigManager metricsConfigManager; 69 | 70 | public boolean hasConsent() { 71 | return this.metricsConfigManager.getCollectionState(this.container).asBoolean(); 72 | } 73 | -------------------------------------------------------------------------------- /source/ore/routes/deploy-version.rst: -------------------------------------------------------------------------------- 1 | ====================== 2 | Deploy Project Version 3 | ====================== 4 | 5 | **POST /api/v1/projects/:pluginId/versions/:version** 6 | 7 | Deploys a new version for the specified project. The body should be sent as ``multipart/form-data`` with the fields 8 | shown below. Returns a JSON representation of the deployed version. 9 | 10 | +-------------+-----------+----------------------------------------------------------------+ 11 | | Name | Data Type | Description | 12 | +=============+===========+================================================================+ 13 | | apiKey | String | An Ore deployment key obtained through the Ore settings. | 14 | +-------------+-----------+----------------------------------------------------------------+ 15 | | channel | String | The channel the version should be in. | 16 | +-------------+-----------+----------------------------------------------------------------+ 17 | | recommended | Boolean | If this version should be set as the recommended version. | 18 | | | | Defaults to true. | 19 | +-------------+-----------+----------------------------------------------------------------+ 20 | | forumPost | Boolean | Whether a forum post should be created or not. If no value is | 21 | | | | specified, it will default to the project's setting. Optional. | 22 | +-------------+-----------+----------------------------------------------------------------+ 23 | | changelog | String | A changelog to include for this version. Optional. | 24 | +-------------+-----------+----------------------------------------------------------------+ 25 | | pluginFile | File | The plugin file to upload. | 26 | +-------------+-----------+----------------------------------------------------------------+ 27 | | pluginSig | File | A signature of the plugin file. | 28 | +-------------+-----------+----------------------------------------------------------------+ 29 | 30 | **Example curl usage:** 31 | 32 | .. code-block:: bash 33 | 34 | curl -F "apiKey=string" -F "apiKey=string" -F "channel=string" -F "recommended=boolean" \ 35 | -F "forumPost=boolean" -F "changelog=string" -F pluginFile=@localPluginFile \ 36 | -F pluginSig=@localpluginSig https://ore.spongepowered.org/api/v1/projects/:pluginId/versions/:version 37 | 38 | **Example output:** 39 | 40 | .. code-block:: json 41 | 42 | { 43 | "id": 1226, 44 | "createdAt": "2018-02-08 18:41:36.917", 45 | "name": "1.1", 46 | "dependencies": [{ 47 | "pluginId": "spongeapi", 48 | "version": "7.1.0" 49 | }], 50 | "pluginId": "auction", 51 | "channel": { 52 | "name": "Release", 53 | "color": "#009600" 54 | }, 55 | "fileSize": 11441, 56 | "md5": "d169809b0eda0e5d49bc60d5f69f097b", 57 | "staffApproved": false, 58 | "href": "/ewoutvs_/Auction/versions/1.1", 59 | "tags": [{ 60 | "id": 13, 61 | "name": "Sponge", 62 | "data": "7.1.0", 63 | "backgroundColor": "#F7Cf0D", 64 | "foregroundColor": "#000000" 65 | }], 66 | "downloads": 26, 67 | "author": "ewoutvs_" 68 | } 69 | -------------------------------------------------------------------------------- /source/server/management/plugins.rst: -------------------------------------------------------------------------------- 1 | ================== 2 | Installing Plugins 3 | ================== 4 | 5 | What Are Plugins 6 | ================ 7 | 8 | Plugins are files written in Java that change the way the server works, generally adding features. They allow server 9 | owners to do a lot of modifications, such as adding an economy system, managing teleports and permissions, etc. 10 | 11 | Finding Plugins 12 | =============== 13 | 14 | .. warning:: 15 | Do not download plugins from untrustworthy sources! Malicious plugins can be used to give others unauthorized access 16 | to your server or computer. 17 | 18 | SpongePowered currently runs the `Ore platform `_ to make it easy for plugin developers 19 | and users to distribute and download plugins. Alternatively, you can search for plugins on the 20 | `SpongePowered forums `_. 21 | 22 | Installation 23 | ============ 24 | 25 | SpongeForge 26 | ~~~~~~~~~~~ 27 | 28 | In order to install plugins, place them into the ``/mods/`` folder of your game or server directory. If your download 29 | came in a .zip file, then you may need to extract it to find a .jar file inside. 30 | 31 | You can also place your plugins inside the ``/mods/plugins/`` subfolder or even set a custom folder in the 32 | :doc:`global.conf<../getting-started/configuration/sponge-conf>` file via the ``plugins-dir`` setting. SpongeForge will 33 | automatically search these folders for plugins. Please note that plugins which make use of ``Mixins`` *must* reside 34 | inside the ``mods`` folder. 35 | 36 | SpongeVanilla 37 | ~~~~~~~~~~~~~ 38 | 39 | .. note:: 40 | For consistency between SpongeForge and SpongeVanilla, plugins are stored in the mods directory on SpongeVanilla. 41 | 42 | In order to install plugins, place them into the ``/mods/`` folder of your game or server directory. If your download 43 | came in a .zip file, then you may need to extract it to find a .jar file inside. 44 | 45 | You can also place your plugins inside the ``/mods/plugins/`` subfolder or even set a custom folder in the 46 | :doc:`global.conf<../getting-started/configuration/sponge-conf>` file via the ``plugins-dir`` setting. SpongeVanilla 47 | will automatically search these folders for plugins. Please note that plugins which make use of ``Mixins`` *must* reside 48 | inside the ``mods`` folder. 49 | 50 | Common Problems 51 | =============== 52 | 53 | If you are having problems with a plugin, consider the following things: 54 | 55 | * Is the plugin compatible with your Minecraft version? While Sponge tries to keep old plugins working, this is 56 | sometimes not possible. In most cases, plugins based on a stable release should continue functioning without being 57 | updated. Please note that plugins might stop working if you switch to a different major version of the API, since 58 | major versions contain breaking changes. Refer to our :doc:`versioning scheme <../../contributing/versioning>` for 59 | more information. 60 | * Do you run a current Java version? Sponge is built for Java 8 and is known to trigger a bug in the JRE 1.8.0_20, so 61 | make sure you use a version newer than that. 62 | * The plugin may be outdated. Is there a newer version of the plugin? 63 | * Does the plugin need a specific implementation and/or build of Sponge? Some plugins may bypass the Sponge API, or 64 | otherwise rely on details that change between versions or platforms. Check at the site you downloaded it from. 65 | -------------------------------------------------------------------------------- /source/versions/legacy-versions.rst: -------------------------------------------------------------------------------- 1 | ============================= 2 | Older Versions of SpongeForge 3 | ============================= 4 | 5 | .. note:: 6 | 7 | Our versioning policy was updated in October 2018. **Prior to** SpongeAPI 7.1, the following information applies. 8 | See :doc:`filenames` for information on newer versions. 9 | 10 | The format of the SpongeForge download filename is: 11 | ``spongeforge----BETA-.jar`` 12 | 13 | +----------------------+-----------------------------------------------------------------------------------------------+ 14 | | ``MCVersion`` | The Minecraft version. Only clients compatible with this version can connect. | 15 | +----------------------+-----------------------------------------------------------------------------------------------+ 16 | | ``ForgeBuild`` | The Forge build that SpongeForge is built against and is guaranteed to be compatible | 17 | +----------------------+-----------------------------------------------------------------------------------------------+ 18 | | ``SpongeAPIVersion`` | The version of SpongeAPI implemented by this file. This is what Sponge plugins depend on. | 19 | +----------------------+-----------------------------------------------------------------------------------------------+ 20 | | ``SpongeBuildId`` | The build number of Sponge. This is what you should supply when reporting bugs or seeking | 21 | | | support. | 22 | +----------------------+-----------------------------------------------------------------------------------------------+ 23 | 24 | The Forge Build in the filename specifies the version of Forge this version of SpongeForge used during development and 25 | testing. The two versions are guaranteed to work without any issues. We **tend** to use the latest *Recommended Build* 26 | of Forge for this purpose. 27 | 28 | .. note:: 29 | 30 | Normal Forge mods can usually run on any build of Forge for a given Minecraft version (e.g. 1.12.2) without any 31 | problem. However, SpongeForge needs to access, among other things, internal parts of Forge, which most mods 32 | shouldn’t be touching, let alone modifying as Sponge does. Since Forge is free to change their internal code 33 | whenever they want to, its normal guarantee of backwards-compatibility doesn’t apply to SpongeForge. Feel free to 34 | use more recent versions of Forge than the one used for SpongeForge, but we can't always guarantee compatibility. 35 | 36 | .. warning:: 37 | 38 | When investigating crash issues, you can freely try newer versions of Forge than listed on the SpongeForge Jar. 39 | However, it is recommended to also check with the matching version, to make sure your issue is not related to a 40 | version mismatch. 41 | Even though there will be no guarantee of compatibility, please report any breakage to the issue tracker, so that 42 | SpongeForge can be updated. 43 | 44 | Example 45 | ------- 46 | 47 | SpongeForge Jar files will always follow this naming scheme, to allow you to easily identify compatibility. 48 | 49 | For example, the file name ``spongeforge-1.12.2-2705-7.1.0-BETA-3442.jar`` is compatible with Minecraft version 50 | ``1.12.2``, was built with Forge ``14.23.4.2705`` (Build ``2705``), provides SpongeAPI ``7.1.0`` and was build number 51 | ``3442`` of SpongeForge. 52 | -------------------------------------------------------------------------------- /source/contributing/implementation/debugging/testing.rst: -------------------------------------------------------------------------------- 1 | ======================= 2 | Testing Plugins or Mods 3 | ======================= 4 | 5 | .. note:: 6 | The changes made by your PR determines whether you need to provide a testing plugin or a testing mod. Any changes 7 | to the API require a testing *plugin*, and any changes to implementation need a testing *mod*. Test plugin will 8 | refer to both for the remainder of this article. 9 | 10 | Testing is an integral part of any software development project. Supplying a test plugin accomplishes two goals: 11 | 12 | 1. Testing 13 | 14 | A test plugin demonstrates you have tested your changes, but it also provides others with the ability to check the 15 | current changes as well as future changes. 16 | 17 | #. Documentation 18 | 19 | A well-commented test plugin provides details not necessarily required in PR documentation. Furthermore, comments 20 | in a PR generally last until the PR is merged. Comments in a program last as long as the code remains. They should 21 | not provide all of the documentation. Instead, well-commented code supports and completes the documentation. 22 | 23 | .. tip:: 24 | A good understanding of :doc:`/plugin/index` provides a solid foundation for writing test plugins. Plugin 25 | requirements apply to test plugins, such as :doc:`/plugin/plugin-identifier` and :doc:`/plugin/logging`. 26 | 27 | You should provide a test plugin when you are contributing new or modified feature(s) to the API or implementation. The 28 | plugin is simply a class added to the package ``org.spongepowered.test``, which is found in the 29 | ``SpongeCommon/testplugins/src/main/java/org/spongepowered/test/`` directory. The PR for the contributions should 30 | include the test plugin. 31 | 32 | It is essential that test plugins do not change the game when not intended. As a result, a command should toggle the 33 | plugin functionality. Be sure not to confuse this with **excluding** the test plugins in the build process. A setting 34 | in ``SpongeCommon/gradle/implementation.gradle`` can exclude test plugins from the resulting jar file. However, a 35 | command must toggle the functionality of the test plugin whether or not test plugins get included in a jar file or not. 36 | 37 | .. note:: 38 | ``@Plugin`` will automatically register your plugin with Sponge, but it will not allow it to be toggled. 39 | 40 | The following code demonstrates registering your plugin and allowing it to be toggled: 41 | 42 | .. code-block:: java 43 | 44 | private boolean registered = false; 45 | 46 | @Listener 47 | public void onInit(GameInitializationEvent event) { 48 | Sponge.getCommandManager().register(this, 49 | CommandSpec.builder().executor((source, context) -> { 50 | if (this.registered) { 51 | this.registered = false; 52 | Sponge.getEventManager().unregisterListeners(this.listener); 53 | } else { 54 | this.registered = true; 55 | Sponge.getEventManager().registerListeners(this, this.listener); 56 | } 57 | return CommandResult.success(); 58 | }).build(), "flowerPotTest"); 59 | } 60 | 61 | 62 | .. note:: 63 | JUnit is used on a limited basis and primarily for internal purposes. Generally speaking, JUnit is useful for 64 | testing without a player. However, the best practice is not to use JUnit unless you have agreement from a Sponge 65 | staff member. 66 | -------------------------------------------------------------------------------- /source/plugin/project/version-numbers.rst: -------------------------------------------------------------------------------- 1 | Version Numbers 2 | =============== 3 | 4 | Your plugin needs a unique version number in order to allow humans to find out which version of a plugin is the 5 | successor of the other. There are plenty of versioning schemes that you could use for your own plugin. In the following 6 | part, we explain a few concepts with their pros and cons. 7 | 8 | Sponge recommends using a version identifier that consists of either two or three numeric version parts separated with 9 | a ``.`` and additional label appended with a hyphen ``-`` such as ``3.1`` or ``1.0.3-API7`` similar to SemVer. 10 | Start with ``1.x`` if your plugin is ready. Start with ``0.x`` if your plugin is not yet ready or unstable. 11 | 12 | .. note:: 13 | 14 | While Sponge recommends using the above versioning scheme, plugin authors are free to choose their own. Please keep 15 | in mind that your users have to deal with a multitude of versioning schemes, so keep it simple. 16 | 17 | SemVer 18 | ------ 19 | 20 | `SemVer `_ is a commonly used semantic versioning scheme. It consists of three numeric blocks that 21 | are separated by dots and additional labels which are appended using hyphens. The three numeric blocks make up 22 | the ``MAJOR``, ``MINOR`` and ``PATCH`` version parts. 23 | 24 | * A change in the **MAJOR** version indicates that you made incompatible API changes. Rewriting large parts of your 25 | plugin or the entire plugin would also count as incompatible changes. 26 | * A change in **MINOR** version indicates that a feature has been added without breaking backward compatibility. 27 | * A change in the **PATCH** version indicates that some bugs have been fixed. 28 | 29 | The labels can be used to mark builds as pre-releases or contain build metadata such as the supported Minecraft version. 30 | If you increase one part of the version, then you will set the following parts back to zero. Using this strategy you 31 | can find the latest version by comparing the version blocks with each other; however, this scheme does not contain any 32 | information about the release order for versions which differ in two version number blocks. Example: Version ``1.0.9`` 33 | would be released after ``1.0.8``, but version ``1.1.0`` could be released before, after or even at the same time as 34 | either of them. 35 | 36 | .. note:: 37 | 38 | The SpongeAPI uses this versioning scheme. 39 | 40 | **Examples** 41 | 42 | * ``0.1.0`` 43 | * ``1.0.0`` 44 | * ``1.1.0-SNAPSHOT`` 45 | * ``3.12.21-API7`` 46 | 47 | **Pros** 48 | 49 | * Easy to read and understand 50 | 51 | **Cons** 52 | 53 | * Mostly API oriented so the terms don't really apply if you don't provide an API in your plugin. 54 | 55 | Timestamp 56 | --------- 57 | 58 | This is a less commonly used versioning scheme, but it is also a very simple one, as it does not contain any additional 59 | information in the version numbers. It does not matter which separators you use (if any) or which date and time parts 60 | you include. However, we recommend ordering date and time parts in descending order of duration like ``YYYY-MM-DD``. 61 | If you sort your files alphabetically, please make sure that the order would be the same as the version order. It is 62 | also possible to add a build qualifier or a build number. 63 | 64 | **Examples** 65 | 66 | * ``18.01.31`` 67 | * ``v2018-05-29.1`` 68 | * ``2018.01.13-SNAPHOT`` 69 | 70 | **Pros** 71 | 72 | * Easy to read and understand 73 | 74 | **Cons** 75 | 76 | * Does not contain any information about compatibility. 77 | 78 | Other 79 | ----- 80 | 81 | You can read more about Software versioning and versioning schemes 82 | `online `_. 83 | -------------------------------------------------------------------------------- /tools/code-checker/src/main/java/org/spongepowered/docs/tools/codeblock/OnOffKeywordPredicate.java: -------------------------------------------------------------------------------- 1 | /* 2 | * This file is part of SpongeAPI, licensed under the MIT License (MIT). 3 | * 4 | * Copyright (c) SpongePowered 5 | * Copyright (c) contributors 6 | * 7 | * Permission is hereby granted, free of charge, to any person obtaining a copy 8 | * of this software and associated documentation files (the "Software"), to deal 9 | * in the Software without restriction, including without limitation the rights 10 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 11 | * copies of the Software, and to permit persons to whom the Software is 12 | * furnished to do so, subject to the following conditions: 13 | * 14 | * The above copyright notice and this permission notice shall be included in 15 | * all copies or substantial portions of the Software. 16 | * 17 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 23 | * THE SOFTWARE. 24 | */ 25 | package org.spongepowered.docs.tools.codeblock; 26 | 27 | import java.util.function.Predicate; 28 | 29 | /** 30 | * Predicate that will filter the content based on the preceding on and off 31 | * keywords. Entries that match the on keyword will pass the filter. Entries 32 | * that match the off keyword will be removed. 33 | * 34 | * @param The type of data this predicate deals this. 35 | */ 36 | public class OnOffKeywordPredicate implements Predicate { 37 | 38 | private final Predicate onKeyword; 39 | private final Predicate offKeyword; 40 | private boolean status = false; 41 | 42 | /** 43 | * Creates an new OnOffKeywordPredicate that will return all entries that 44 | * were tested while this instances was on. The initial status will be off. 45 | * 46 | * @param onKeyword The predicate used to decide to start letting entries 47 | * throughout. 48 | * @param offKeyword The predicate used to decide to stop letting entries 49 | * throughout. 50 | */ 51 | public OnOffKeywordPredicate(Predicate onKeyword, Predicate offKeyword) { 52 | this(onKeyword, offKeyword, false); 53 | } 54 | 55 | /** 56 | * Creates an new OnOffKeywordPredicate that will return all entries that 57 | * were tested while this instances was on. 58 | * 59 | * @param onKeyword The predicate used to decide to start letting entries 60 | * throughout. 61 | * @param offKeyword The predicate used to decide to stop letting entries 62 | * throughout. 63 | * @param initialStatus The initial status of this filter. 64 | */ 65 | public OnOffKeywordPredicate(Predicate onKeyword, Predicate offKeyword, boolean initialStatus) { 66 | this.onKeyword = onKeyword; 67 | this.offKeyword = offKeyword; 68 | this.status = initialStatus; 69 | } 70 | 71 | @Override 72 | public boolean test(T t) { 73 | if (this.status) { 74 | if (this.offKeyword.test(t)) { 75 | this.status = false; 76 | } 77 | } else { 78 | if (this.onKeyword.test(t)) { 79 | this.status = true; 80 | } 81 | } 82 | return this.status; 83 | } 84 | 85 | } 86 | -------------------------------------------------------------------------------- /source/plugin/economy/practices.rst: -------------------------------------------------------------------------------- 1 | ========================== 2 | Economy API Best Practices 3 | ========================== 4 | 5 | .. javadoc-import:: 6 | org.spongepowered.api.service.economy.transaction.ResultType 7 | org.spongepowered.api.service.economy.transaction.TransactionResult 8 | 9 | The Economy API tries to be abstract enough to give economy plugins flexibility in how they operate. 10 | In order to give economy plugins as much control as possible, plugins consuming the Economy API should 11 | follow some guidelines when working with it: 12 | 13 | Withdrawing money 14 | ================= 15 | 16 | Plugins should *not* check if an account has enough money before attempting to withdraw it. While this may 17 | sound counter-intuitive, it allows economy plugins to fully control how they handle negative balances. 18 | 19 | By checking yourself if the account has enough money, you prevent the economy plugin from (potentially) allowing a 20 | negative balance. For example, one economy plugin might want to allow negative balances to admins, or players with a 21 | certain permission. By performing the check yourself, you take this power away from the economy plugin. 22 | 23 | This code illustrates what **not** to do: 24 | 25 | .. code-block:: java 26 | 27 | import java.math.BigDecimal; 28 | 29 | import org.spongepowered.api.event.cause.Cause; 30 | import org.spongepowered.api.event.cause.EventContext; 31 | import org.spongepowered.api.event.cause.EventContextKeys; 32 | import org.spongepowered.api.service.economy.EconomyService; 33 | import org.spongepowered.api.service.economy.account.Account; 34 | 35 | PluginContainer plugin = ...; 36 | EconomyService service = ...; 37 | Account account = ...; 38 | BigDecimal requiredAmount = BigDecimal.valueOf(20); 39 | EventContext eventContext = EventContext.builder().add(EventContextKeys.PLUGIN, plugin).build(); 40 | 41 | // BAD: Don't perform this check 42 | if (account.getBalance(service.defaultCurrency()).compareTo(requiredAmount) < 0) { 43 | // You don't have enough money! 44 | } else { 45 | // The account has enough, let's withdraw some cash! 46 | account.withdraw(service.defaultCurrency(), requiredAmount, Cause.of(eventContext, plugin)); 47 | } 48 | 49 | 50 | Instead of this, the best thing to do is simply withdraw the amount you need, and check the :javadoc:`ResultType` of 51 | the returned :javadoc:`TransactionResult`. An economy plugin which doesn't want to allow negative balances will simply 52 | return :javadoc:`ResultType#ACCOUNT_NO_FUNDS`, or :javadoc:`ResultType#FAILED` in this case. 53 | 54 | Here's how you **should** withdraw money: 55 | 56 | .. code-block:: java 57 | 58 | import org.spongepowered.api.event.cause.Cause; 59 | import org.spongepowered.api.event.cause.EventContext; 60 | import org.spongepowered.api.event.cause.EventContextKeys; 61 | import org.spongepowered.api.service.economy.transaction.ResultType; 62 | import org.spongepowered.api.service.economy.transaction.TransactionResult; 63 | 64 | PluginContainer plugin = ...; 65 | EconomyService service = ...; 66 | Account account = ...; 67 | BigDecimal requiredAmount = BigDecimal.valueOf(20); 68 | EventContext eventContext = EventContext.builder().add(EventContextKeys.PLUGIN, plugin).build(); 69 | 70 | TransactionResult result = account.withdraw(service.getDefaultCurrency(), requiredAmount, 71 | Cause.of(eventContext, plugin)); 72 | if (result.result() == ResultType.SUCCESS) { 73 | // Success! 74 | } else if (result.result() == ResultType.FAILED || result.result() == ResultType.ACCOUNT_NO_FUNDS) { 75 | // Something went wrong! 76 | } else { 77 | // Handle other conditions 78 | } 79 | --------------------------------------------------------------------------------