<!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>Plugin Metadata — 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="Ray Tracing" href="ray-tracing.html"/> <link rel="prev" title="Tab Lists" href="tab-lists.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"><a class="reference internal" href="configuration/index.html">Configuring Plugins</a></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 current"><a class="current reference internal" href="#">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>Plugin Metadata</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/SpongePowered/SpongeDocs/blob/Update-to-API6/source/plugin/plugin-meta.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="plugin-metadata">
<h1>Plugin Metadata<a class="headerlink" href="#plugin-metadata" title="Permalink to this headline">¶</a></h1>
<p>Adding plugin metadata helps users to identify your plugin more easily by giving them the ability to check the name,
version, description, or even the authors of a plugin at runtime. It will also be used when publishing plugins on a plugin
portal like <a class="reference external" href="https://github.com/SpongePowered/Ore">Ore</a>.</p>
<p>Currently, Sponge supports the following types of plugin metadata:</p>
<ul class="simple">
<li>Plugin ID, Plugin Name, Version</li>
<li>Description</li>
<li>URL (e.g. Website)</li>
<li>Authors</li>
<li>Plugin dependencies</li>
</ul>
<div class="section" id="plugin-annotation">
<h2>Plugin annotation<a class="headerlink" href="#plugin-annotation" title="Permalink to this headline">¶</a></h2>
<p>You can define the additional (optional) plugin metadata on your <code class="docutils literal"><span class="pre">@Plugin</span></code> annotation:</p>
<div class="highlight-java"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">org.spongepowered.api.plugin.Plugin</span><span class="o">;</span>
<span class="nd">@Plugin</span><span class="o">(</span><span class="n">id</span> <span class="o">=</span> <span class="s">"myplugin"</span><span class="o">,</span> <span class="n">name</span> <span class="o">=</span> <span class="s">"My Plugin"</span><span class="o">,</span> <span class="n">version</span> <span class="o">=</span> <span class="s">"1.0"</span><span class="o">,</span>
<span class="n">description</span> <span class="o">=</span> <span class="s">"This is a very cool plugin I made for me"</span><span class="o">,</span>
<span class="n">url</span> <span class="o">=</span> <span class="s">"http://example.com"</span><span class="o">,</span>
<span class="n">authors</span> <span class="o">=</span> <span class="o">{</span><span class="s">"Spongie"</span><span class="o">,</span> <span class="s">"FLARD"</span><span class="o">},</span>
<span class="n">dependencies</span> <span class="o">=</span> <span class="nd">@Dependency</span><span class="o">(</span><span class="n">id</span> <span class="o">=</span> <span class="s">"otherplugin"</span><span class="o">,</span> <span class="n">optional</span> <span class="o">=</span> <span class="kc">true</span><span class="o">))</span>
</pre></div>
</div>
</div>
<div class="section" id="file-metadata">
<h2>File metadata<a class="headerlink" href="#file-metadata" title="Permalink to this headline">¶</a></h2>
<p>Additionally to plugin metadata defined in the plugin annotation we also recommend plugins to include this metadata in
an extra file in the JAR, which has several advantages:</p>
<ul class="simple">
<li>Easier integration for build systems (e.g. contributing the version from the build system into plugin metadata)</li>
<li>Easier for plugin portals to obtain the plugin metadata (no parsing of class files necessary)</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><strong>We strongly recommend public plugins to include file metadata.</strong> Plugin portals such as <a class="reference external" href="https://github.com/SpongePowered/Ore">Ore</a> may require
file metadata. See <a class="reference internal" href="#using-the-annotation-processor">Using the Annotation Processor</a> for a simple way to generate it. The
implementation may print a warning if a plugin is missing file metadata.</p>
</div>
<div class="section" id="the-mcmod-info-format">
<h3>The mcmod.info format<a class="headerlink" href="#the-mcmod-info-format" title="Permalink to this headline">¶</a></h3>
<p>For Sponge plugins, we use a file called <code class="docutils literal"><span class="pre">mcmod.info</span></code>, which is included in the root of your plugin JAR. The format
originates from Forge, and has been used by several projects in the Minecraft community, so we have chosen to use the same.</p>
<p><code class="docutils literal"><span class="pre">mcmod.info</span></code> is basically a simple <a class="reference external" href="https://en.wikipedia.org/wiki/JSON">JSON</a> file which defines the plugin metadata as simple fields. Here is an example
file that could be used by a Sponge plugin:</p>
<div class="highlight-json"><div class="highlight"><pre><span></span><span class="p">[{</span>
<span class="nt">"modid"</span><span class="p">:</span> <span class="s2">"myplugin"</span><span class="p">,</span>
<span class="nt">"name"</span><span class="p">:</span> <span class="s2">"My Plugin"</span><span class="p">,</span>
<span class="nt">"version"</span><span class="p">:</span> <span class="s2">"1.0"</span><span class="p">,</span>
<span class="nt">"description"</span><span class="p">:</span> <span class="s2">"This is a very cool plugin I made for me"</span><span class="p">,</span>
<span class="nt">"authorList"</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">"Spongie"</span><span class="p">,</span>
<span class="s2">"FLARD"</span>
<span class="p">],</span>
<span class="nt">"dependencies"</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">"otherplugin"</span>
<span class="p">]</span>
<span class="p">}]</span>
</pre></div>
</div>
</div>
<div class="section" id="using-the-annotation-processor">
<h3>Using the Annotation Processor<a class="headerlink" href="#using-the-annotation-processor" title="Permalink to this headline">¶</a></h3>
<p>Writing an extra file is quite annoying. Fortunately, usually there is nothing extra you need to do. When compiling
your plugin, SpongeAPI is able to generate this file automatically based on the information provided in your
<code class="docutils literal"><span class="pre">@Plugin</span></code> annotation.</p>
<div class="section" id="enabling">
<h4>Enabling<a class="headerlink" href="#enabling" title="Permalink to this headline">¶</a></h4>
<p>If you’re using a build system such as Gradle or Maven and have not explicitly disabled annotation processing there is
nothing extra you need to do. By default the annotation processor will automatically run and generate a <code class="docutils literal"><span class="pre">mcmod.info</span></code>
file based on the contents of your <code class="docutils literal"><span class="pre">@Plugin</span></code> annotation.</p>
<p>If you’re not using a build system you need to manually enable annotation processing.</p>
</div>
<div class="section" id="build-system-integration">
<h4>Build system integration<a class="headerlink" href="#build-system-integration" title="Permalink to this headline">¶</a></h4>
<p>If you’re using Gradle, <a class="reference external" href="start/project/gradle">SpongeGradle</a> will provide additional integration for Gradle and
plugin metadata. For example, it will automatically include the project version defined in the Gradle build script in
your plugin metadata. See <a class="reference internal" href="project/gradle.html"><span class="doc">Setting Up Gradle</span></a> for details.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="ray-tracing.html" class="btn btn-neutral float-right" title="Ray Tracing" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="tab-lists.html" class="btn btn-neutral" title="Tab Lists" 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/plugin-meta.rst">Source</a></dd>
<dd><a href="https://github.com/SpongePowered/SpongeDocs/edit/Update-to-API6/source/plugin/plugin-meta.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>