<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Configuring Plugins — Sponge 6.0.0 documentation</title>
<link rel="shortcut icon" href="../../_static/favicon.ico"/>
<link rel="stylesheet" href="../../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../../_static/spongedocs.css" type="text/css" />
<link rel="index" title="Index"
href="../../genindex.html"/> <link rel="search" title="Search" href="../../search.html"/> <link rel="top" title="Sponge 6.0.0 documentation" href="../../index.html"/> <link rel="up" title="Creating a Plugin" href="../index.html"/> <link rel="next" title="Configuration Loaders" href="loaders.html"/> <link rel="prev" title="The Asset API" href="../assets.html"/>
<!-- Google Analytics -->
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-59476017-2', 'auto');
ga('send', 'pageview');
</script>
<script src="../../_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<div id="sp-logo-container" class="page-scroll">
<a class="logo" href="../../index.html">
<img src="../../_static/spongie-mark-dark.svg">
<span>Sponge</span>
<i class="fa fa-fw fa-chevron-down"></i>
</a>
<div id="sp-logo-menu">
<ul id="sp-logo-dropdown">
<li><a href="https://www.spongepowered.org"><i class="fa-fw fa fa-home"></i>Homepage</a></li>
<li><a href="https://forums.spongepowered.org"><i class="fa-fw fa fa-comments"></i>Forums</a></li>
<li><a href="https://github.com/SpongePowered"><i class="fa-fw fa fa-code"></i>Code</a></li>
<li class="active"><a href="https://docs.spongepowered.org"><i class="fa-fw fa fa-book"></i>Docs</a></li>
<li><a href="https://jd.spongepowered.org"><i class="fa-fw fa fa-graduation-cap"></i>Javadocs</a></li>
<li><a href="https://forums.spongepowered.org/c/plugins/plugin-releases"><i class="fa-fw fa fa-plug"></i>Plugins</a></li>
<li><a href="https://www.spongepowered.org/downloads"><i class="fa-fw fa fa-download"></i>Downloads</a></li>
<li><a href="https://www.spongepowered.org/chat"><i class="fa-fw fa fa-comment"></i>Chat</a></li>
</ul>
</div>
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div> </div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../server/index.html">Creating a Server</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../preparing/index.html">Preparing for Development</a></li>
</ul>
<ul class="current">
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">Creating a Plugin</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../buildsystem.html">Build Systems</a></li>
<li class="toctree-l2"><a class="reference internal" href="../workspace/index.html">Setting Up Your Workspace</a></li>
<li class="toctree-l2"><a class="reference internal" href="../project/index.html">Setting Up Your Project</a></li>
<li class="toctree-l2"><a class="reference internal" href="../plugin-identifier.html">Plugin Identifiers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../plugin-class.html">Main Plugin Class</a></li>
<li class="toctree-l2"><a class="reference internal" href="../lifecycle.html">Plugin Lifecycle</a></li>
<li class="toctree-l2"><a class="reference internal" href="../injection.html">Dependency Injection</a></li>
<li class="toctree-l2"><a class="reference internal" href="../practices.html">Best Practices</a></li>
<li class="toctree-l2"><a class="reference internal" href="../optional/index.html">Optionals</a></li>
<li class="toctree-l2"><a class="reference internal" href="../logging.html">Logging and Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../commands/index.html">Commands</a></li>
<li class="toctree-l2"><a class="reference internal" href="../event/index.html">Events</a></li>
<li class="toctree-l2"><a class="reference internal" href="../assets.html">The Asset API</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Configuring Plugins</a><ul>
<li class="toctree-l3"><a class="reference internal" href="loaders.html">Configuration Loaders</a></li>
<li class="toctree-l3"><a class="reference internal" href="nodes.html">Configuration Nodes</a></li>
<li class="toctree-l3"><a class="reference internal" href="serialization.html">Serializing Objects</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../text/index.html">Text</a></li>
<li class="toctree-l2"><a class="reference internal" href="../data/index.html">The Data API</a></li>
<li class="toctree-l2"><a class="reference internal" href="../blocks/index.html">Blocks</a></li>
<li class="toctree-l2"><a class="reference internal" href="../entities/index.html">Entities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../items/index.html">Items</a></li>
<li class="toctree-l2"><a class="reference internal" href="../trade-offers.html">Trade-Offers</a></li>
<li class="toctree-l2"><a class="reference internal" href="../effects.html">Effects</a></li>
<li class="toctree-l2"><a class="reference internal" href="../scheduler.html">Scheduler</a></li>
<li class="toctree-l2"><a class="reference internal" href="../services.html">Services</a></li>
<li class="toctree-l2"><a class="reference internal" href="../database.html">Databases</a></li>
<li class="toctree-l2"><a class="reference internal" href="../permissions.html">Permissions</a></li>
<li class="toctree-l2"><a class="reference internal" href="../bans.html">Bans</a></li>
<li class="toctree-l2"><a class="reference internal" href="../bookview.html">Book Views</a></li>
<li class="toctree-l2"><a class="reference internal" href="../economy/index.html">Economy</a></li>
<li class="toctree-l2"><a class="reference internal" href="../wgen/index.html">World Generation</a></li>
<li class="toctree-l2"><a class="reference internal" href="../manager.html">Plugin Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../game-profile-manager.html">Game Profile Manager</a></li>
<li class="toctree-l2"><a class="reference internal" href="../offline-userplayer-data.html">Offline Player Data</a></li>
<li class="toctree-l2"><a class="reference internal" href="../debugging.html">Plugin Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tab-lists.html">Tab Lists</a></li>
<li class="toctree-l2"><a class="reference internal" href="../plugin-meta.html">Plugin Metadata</a></li>
<li class="toctree-l2"><a class="reference internal" href="../ray-tracing.html">Ray Tracing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../tutorials.html">Tutorials</a></li>
<li class="toctree-l2"><a class="reference internal" href="../internals/index.html">Implementation-dependent Plugins</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../ore/index.html">Ore Documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../contributing/index.html">Contributing to Sponge</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../about/index.html">About the Sponge Project</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../index.html">Sponge</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../index.html">Docs</a> »</li>
<li><a href="../index.html">Creating a Plugin</a> »</li>
<li>Configuring Plugins</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/SpongePowered/SpongeDocs/blob/Update-to-API6/source/plugin/configuration/index.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="configuring-plugins">
<h1>Configuring Plugins<a class="headerlink" href="#configuring-plugins" title="Permalink to this headline">¶</a></h1>
<p>Configuration files allow plugins to store data, as well as allow server administrators to easily take control over
specific portions of a plugin, if you so choose to let them. Sponge uses Configurate to allow you to easily
manipulate configuration files. These pages will explain how to utilize Configurate in order to use configuration
files to full advantage.</p>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">See the official <a class="reference external" href="https://github.com/zml2008/configurate/wiki">Configurate wiki</a> to gain more in-depth information
about working with its components.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Sponge makes use of the HOCON configuration format, a superset of JSON, as the default format for saving
configuration files. The rest of this guide will assume you are using HOCON as well. See
<a class="reference internal" href="../../server/getting-started/configuration/hocon.html"><span class="doc">Introduction to HOCON</span></a> more for information regarding the HOCON format.
Working with different formats is made relatively similar by the Configurate system, so it should not
pose too much of an issue if you use an alternate format instead.</p>
</div>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="loaders.html">Configuration Loaders</a></li>
<li class="toctree-l1"><a class="reference internal" href="nodes.html">Configuration Nodes</a></li>
<li class="toctree-l1"><a class="reference internal" href="serialization.html">Serializing Objects</a></li>
</ul>
</div>
<div class="section" id="quick-start">
<h2>Quick Start<a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h2>
<div class="section" id="creating-a-default-plugin-configuration">
<h3>Creating a Default Plugin Configuration<a class="headerlink" href="#creating-a-default-plugin-configuration" title="Permalink to this headline">¶</a></h3>
<p>Plugins using the Sponge API have the option to use one or more configuration files. Configuration files allow plugins
to store data, and they allow server administrators to customize plugin options (if applicable).</p>
</div>
<div class="section" id="getting-your-default-plugin-configuration">
<span id="getting-default-config"></span><h3>Getting your Default Plugin Configuration<a class="headerlink" href="#getting-your-default-plugin-configuration" title="Permalink to this headline">¶</a></h3>
<p>The Sponge API offers the use of the <a class="reference external" href="https://jd.spongepowered.org/6.0.0/org/spongepowered/api/config/DefaultConfig.html">DefaultConfig</a> annotation on a field or setter method with the type
<code class="docutils literal"><span class="pre">Path</span></code> to get the default configuration file for your plugin.</p>
<p>The <code class="docutils literal"><span class="pre">@DefaultConfig</span></code> annotation requires a <code class="docutils literal"><span class="pre">sharedRoot</span></code> boolean. If you set <code class="docutils literal"><span class="pre">sharedRoot</span></code> to <code class="docutils literal"><span class="pre">true</span></code>, then the
returned pathname will be in a shared configuration directory. In that case, the configuration file for your plugin
will be <code class="docutils literal"><span class="pre">your_plugin_id.conf</span></code> (with “your_plugin_id” replaced with your plugin’s specified ID).</p>
<div class="admonition tip">
<p class="first admonition-title">Tip</p>
<p class="last">See <a class="reference internal" href="../plugin-class.html"><span class="doc">Main Plugin Class</span></a> for information on configuring your plugin ID.</p>
</div>
<p>If you set <code class="docutils literal"><span class="pre">sharedRoot</span></code> to <code class="docutils literal"><span class="pre">false</span></code>, the returned pathname will refer to a file named <code class="docutils literal"><span class="pre">{pluginname}.conf</span></code> in a
directory specific to your plugin.</p>
<p>If you are unsure of what to set the value of <code class="docutils literal"><span class="pre">sharedRoot</span></code> to, consider the following:</p>
<ul class="simple">
<li>If you plan on having multiple configuration files (complex plugins) in the future, set the value to <code class="docutils literal"><span class="pre">false</span></code>.</li>
<li>If you plan on having a single configuration file (less-complex plugins), set the value to <code class="docutils literal"><span class="pre">true</span></code>.</li>
</ul>
<p>You can also obtain a <code class="docutils literal"><span class="pre">Path</span></code> instance pointing to the config directory instead of a particular file. Just
have it injected using the <a class="reference external" href="https://jd.spongepowered.org/6.0.0/org/spongepowered/api/config/ConfigDir.html">ConfigDir</a> annotation, either with <code class="docutils literal"><span class="pre">sharedRoot</span></code> set to <code class="docutils literal"><span class="pre">false</span></code> for a plugin
specific directory or to <code class="docutils literal"><span class="pre">true</span></code> to get the shared configuration directory.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">While it may be possible to get a <code class="docutils literal"><span class="pre">File</span></code> instead of a <code class="docutils literal"><span class="pre">Path</span></code>, Configurate (and Sponge) recommend using <code class="docutils literal"><span class="pre">Path</span></code>.</p>
</div>
<p><strong>Example - Field using</strong> <code class="docutils literal"><span class="pre">@DefaultConfig</span></code></p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">java.nio.file.Path</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">com.google.inject.Inject</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.config.ConfigDir</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">org.spongepowered.api.config.DefaultConfig</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">ninja.leaping.configurate.commented.CommentedConfigurationNode</span><span class="o">;</span>
<span class="kn">import</span> <span class="nn">ninja.leaping.configurate.loader.ConfigurationLoader</span><span class="o">;</span>
<span class="nd">@Inject</span>
<span class="nd">@DefaultConfig</span><span class="o">(</span><span class="n">sharedRoot</span> <span class="o">=</span> <span class="kc">true</span><span class="o">)</span>
<span class="kd">private</span> <span class="n">Path</span> <span class="n">defaultConfig</span><span class="o">;</span>
<span class="nd">@Inject</span>
<span class="nd">@DefaultConfig</span><span class="o">(</span><span class="n">sharedRoot</span> <span class="o">=</span> <span class="kc">true</span><span class="o">)</span>
<span class="kd">private</span> <span class="n">ConfigurationLoader</span><span class="o"><</span><span class="n">CommentedConfigurationNode</span><span class="o">></span> <span class="n">configManager</span><span class="o">;</span>
<span class="nd">@Inject</span>
<span class="nd">@ConfigDir</span><span class="o">(</span><span class="n">sharedRoot</span> <span class="o">=</span> <span class="kc">false</span><span class="o">)</span>
<span class="kd">private</span> <span class="n">Path</span> <span class="n">privateConfigDir</span><span class="o">;</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">When your plugin is running for the first time, returned pathnames for configuration files and directories may not
yet exist. If you delegate all reading / writing of files to Configurate, you do not need to worry about
non-existant paths as the library will handle them appropriately.</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The use of YAML format (<a class="reference external" href="http://yaml.org/spec/1.1/">http://yaml.org/spec/1.1/</a>) is also supported, but the preferred config format for Sponge
plugins is HOCON. Conversion from YAML to HOCON can be automated by using a <a class="reference external" href="http://zml2008.github.io/configurate/apidocs/ninja/leaping/configurate/yaml/YAMLConfigurationLoader.html">YAMLConfigurationLoader</a> to
load the old config and then saving it using a <a class="reference external" href="http://zml2008.github.io/configurate/apidocs/ninja/leaping/configurate/hocon/HoconConfigurationLoader.html">HoconConfigurationLoader</a>.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="loaders.html" class="btn btn-neutral float-right" title="Configuration Loaders" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="../assets.html" class="btn btn-neutral" title="The Asset API" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2014-2017, Sponge Contributors.
</p>
</div>Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
<span class="rst-current-version" data-toggle="rst-current-version">
<i class="fa fa-book"> <span>SpongeDocs</span></i>
v: 6.0.0
<span class="fa fa-caret-down"></span>
</span>
<div id="versions" class="rst-other-versions">
<dl>
<dt>Contribute</dt>
<dd><a href="https://github.com/SpongePowered/SpongeDocs/blob/Update-to-API6/source/plugin/configuration/index.rst">Source</a></dd>
<dd><a href="https://github.com/SpongePowered/SpongeDocs/edit/Update-to-API6/source/plugin/configuration/index.rst">Edit</a></dd>
</dl>
</div>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../../',
VERSION:'6.0.0',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script> <script type="text/javascript" src="../../_static/jquery.js"></script> <script type="text/javascript" src="../../_static/underscore.js"></script> <script type="text/javascript" src="../../_static/doctools.js"></script> <script type="text/javascript" src="../../_static/spongedocs.js"></script>
<script type="text/javascript" src="../../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>