This wiki is archived from 2021-09-05

Creating Your First Planetary Annihilation Mod: Difference between revisions

From Planetary Annihilation: TITANS and Classic PA Wiki
Jump to navigation Jump to search
(Created page with "Category:Modding = 50px Creating your first mod = == 50px Introduction == Mods can generally be downloaded from t...")
 
mNo edit summary
 
(54 intermediate revisions by 2 users not shown)
Line 1: Line 1:
[[Category:Modding]]
[[Category:Modding]]
= [[File:Titans-icon.png|50px]] Creating your first mod =
= Creating Your First Planetary Annihilation Mod =


== [[File:platinum-rank-icon.png|50px]] Introduction ==
Released mods are typically installed and downloaded automatically using in-game using [[Planetary Annihilation Community Mods|Community Mods]].
Mods can generally be downloaded from the Community Mods manager built into Planetary Annihilation. However, when developing your own mod, you should start with a local copy for development purposes. Once you are happy with the way the mod works, you can upload it to the Community Mods manager so other players can download it.
 
During mod development and testing local filesystem mods are used.
 
== Mod Identifiers ==


The first step is to pick a Mod Identifier.
{{Mod Identifiers}}
{{Mod Identifiers}}


== [[File:platinum-rank-icon.png|50px]] File structure ==
To avoid conflicts with your released version use a different identifier for your development or test versions. eg com.pa.mikeyh-some-mod-name-dev
Local mods are located in a special directory inside the [[Planetary Annihilation Data Directory]]. If you wish to create [[Client Mods]], make a new subdirectory in the "client_mods" folder. If you want to create [[Server Mods]], create a new subdirectory in the "server_mods" folder. The recommended practise is to use the mod identifier as the name of your new subdirectory.
 
== Mod Directory Structure ==
 
Local filesystem mods are installed in the [[Planetary Annihilation Data Directory]] based on the type of mod:
 
* Client Mods: client_mods (might be mods on very old installs from alpha / beta)
* Server Mods: server_mods
 
Every mod must be contained in a single top level directory with a modinfo.json JSON file as documented in [[Mod Structure]].
 
 
PLEASE DO NO ADD EXTRA PROPERTIES THAT YOU SEE IN DOWNLOADED ZIPS.
 
 
A new game lobby UI client mod would be installed as a filesystem client mod using:
 
* [[Planetary Annihilation Data Directory]]
** client_mods
*** com.pa.mikeyh.some-mod-name
**** modinfo.json
**** ui
***** mods
****** com.pa.mikeyh.some-mod-name
******* new_game.js
 
== Testing Your Mod ==
 
Filesystem mods with a valid modinfo.json installed in the filesystem mod directories will automatically appear in the installed tab of Community Mods in PA.
 
If your mod does not appear check the following:
* modinfo.json is valid JSON with all mandatory properties as documented in [[Mod Structure]] (no extra properties)
* mod directory is in the correct mod directory for its context
 
You can edit modinfo.json then reload file system mods to update your mod info without restating PA.
 
Other file changes typically require a restart of PA.


Inside that new subdirectory, you need to make a new text file called "modinfo.json". This file contains the metadata for your mod, such as your name, the name and type of your mod, and others. The file is formatted in JSON and the fields are described in [[Mod Structure]].
== Example Mods ==
Here is a list of example mods to get you started:
* [[Example Mod Custom Skybox]]
* [[Example Mod Bigger Boom Bot]]
* [[Example Mod Chat Alert]]


== [[File:platinum-rank-icon.png|50px]] Enabling the mod ==
{{Submitting and Updating Your Mod}}
Start Planetary Annihilation and press the Community Mods button. The go to the Installed tab. Your mod should now be visible there. If it is not, check if the modinfo.json you created is valid JSON and contains all of the mandatory fields and press Reload File System Mods.


Click on your mod and press the Enable button. The orange bar in front of your mod name should now change to green, indicating that the mod is active. This means you are good to go and can start developing the mod.
{{ New Mod Submission Offline }}

Latest revision as of 10:44, 9 September 2021

Creating Your First Planetary Annihilation Mod

Released mods are typically installed and downloaded automatically using in-game using Community Mods.

During mod development and testing local filesystem mods are used.

Mod Identifiers

Every mod must have a unique identifier.

The required format is lowercase reverse domain name notation.

eg com.palobby.some-mod-name

If you don't have your own domain or prefer to use your forum / game handle then prefix with com.pa.handle.some-mod-name

eg com.pa.mikeyh.some-mod-name

My personal preference is dashes (-) over underscores (_) for readability.

To avoid conflicts with your released version use a different identifier for your development or test versions. eg com.pa.mikeyh-some-mod-name-dev

Mod Directory Structure

Local filesystem mods are installed in the Planetary Annihilation Data Directory based on the type of mod:

  • Client Mods: client_mods (might be mods on very old installs from alpha / beta)
  • Server Mods: server_mods

Every mod must be contained in a single top level directory with a modinfo.json JSON file as documented in Mod Structure.


PLEASE DO NO ADD EXTRA PROPERTIES THAT YOU SEE IN DOWNLOADED ZIPS.


A new game lobby UI client mod would be installed as a filesystem client mod using:

Testing Your Mod

Filesystem mods with a valid modinfo.json installed in the filesystem mod directories will automatically appear in the installed tab of Community Mods in PA.

If your mod does not appear check the following:

  • modinfo.json is valid JSON with all mandatory properties as documented in Mod Structure (no extra properties)
  • mod directory is in the correct mod directory for its context

You can edit modinfo.json then reload file system mods to update your mod info without restating PA.

Other file changes typically require a restart of PA.

Example Mods

Here is a list of example mods to get you started:

Submitting Your Mod

Before submitting your mod ensure that it is not outputting any errors to either the game's client or server logs.

You must create a forum post in the appropriate forum and link it in your modinfo file:

For released mods please create a post on steam discussions with prefix [MOD]:

The Community Mods server requires a downloadable URL to a ZIP archive of your top level directory containing your modinfo.json and mod files.

A new game lobby UI client mod would be submitted as a downloadable URL to:

  • com.pa.mikeyh.some-mod-name.zip
    • modinfo.json
      • ui
        • mods
          • com.pa.mikeyh.some-mod-name
            • new_game.js

GitHub projects with static download links to a release branch are preferred for auto updating.

eg https://github.com/user/com.pa.mod/archive/release.zip

You can exclude files from the zip using .gitattributes: 

.gitattributes export-ignore
.gitignore export-ignore

If using Dropbox links they must end with dl=1 to be downloadable.

Check the status of your mod at: https://palobby.com/community-mods/

Updating Your Mod

Existing mods will update automatically if you update the existing zip without changing the URL or mod identifier. GitHub will do that automatically.

When changing your mod please remember to update the date and version.

For each update of your mod please post a new comment to your forum and steam discussions posts with any changes then update your original posts.

Check the status of your mod at: https://palobby.com/community-mods/

New Mod Submission

Join the official discord: https://discord.gg/pa and ask to be added to the #mod-submissions channel.

Post the URL to your zip mod in the #mod-submissions channel.

This can't be a link to a download page, it must be a direct link to the zip file.

Existing mods will update automatically if you update the existing zip without changing the URL or mod identifier.

Links to GitHub are preferred.

Retrieved from "https://wiki.palobby.com/w/index.php?title=Creating_Your_First_Planetary_Annihilation_Mod&oldid=3451"