The Endless Sky Developer Guide - Or, 'Should I make a plug-in or a Pull Request?'

The Endless Sky Developer Guide - Or, 'Should I make a plug-in or a Pull Request?'.md

The Endless Sky Developer Guide

Or, 'Should I make a plug-in or a Pull Request?'

by Zitchas

Copyright 2021 CC-BY-SA

If you are considering making content for Endless Sky, let me start by offering my congratulations and enthusiastic support. As a community driven project, it has been very rewarding experience for me to contribute, and the community never fails to inspire me to continue. That said, the decision of whether to create content that will be merged into vanilla (the base game), or to make a plug-in that anyone can choose to have in their game, can be a difficult one.

This guide is intended to help you make that choice, predominantly by asking a series of questions that will help clarify your own intentions and expectations.

Before I get to the questions, though, let me say this: Neither vanilla content nor plug-ins are inherently better or worse than the other. Each has its advantages and disadvantages, and different sorts of content are better suited to one of them or the other. In the questions below, anywhere I talk about "being included in ES" I am referring to being part of the base vanilla game, or in other words, being included in the base distribution. (The questions themselves are in bold.)

1. Endless Sky is an open source project. This means that, legally speaking, everything in Endless Sky is available for anyone to use for any purpose, anywhere, at any time. This includes into packaging parts of the content into a commercial game and selling it for profit (So long as all contributors are attributed in the credits, a small number of "NC" sounds are ommitted, and the source code and data are made freely available). Are you comfortable with this?

2. Endless Sky is a collaborative project, but there are currently only four people with authority (and technical access) to commit changes into the base game. We often call these the "Developers" or "Devs," and they have the final authority over what gets in and what doesn't. In addition to the Devs, there are over 150 people who have submitted code and content to Endless Sky. As a collaborative project, Endless Sky is open for anyone to propose changes, edits, revisions, modifications, replacements, or additions to any part of the game's code and content. This includes whatever you happen to contribute. Are you comfortable with the idea that someone else may propose changes to the content you submit?

3. Once you make a pull request to add your content or code to Endless Sky, you effectively relinquish control over it as it becomes part of the game. Your opinion will definitely be valued when reviewing future content that might affect, change, revise, or otherwise alter what you contributed, but you do not have any kind of veto. Are you comfortable with giving up this control?

4. There is a fair bit of established lore in the game, and sometimes a significant amount of effort is required to make your new material fit in with that lore. Are you willing to make that effort?

5. Many people want to add their favorite ships, outfits, stories, and characters from other science fiction universes. While Easter eggs are acceptable (even fun!), they are legally touchy. As a minimal criterion for inclusion in ES, all the material must meet the legal copyright framework of the game. In layman's terms, this usually boils down to "everything you submit in a PR must be either of your own creation or something you have legal permission to edit and distribute." This means you cannot simply pull a model, character, or text directly out of another source, render it, and submit it for inclusion in Endless Sky; instead, you need to make a new model yourself (or get someone else to for you). So, can you attest that all your material is either of your own creation or material that can legally be distributed under the GPL 3 license?

6. Some people have ideas for content that are awesome, but don't necessarily fit really well within the Endless Sky universe. For the Escape Velocity franchise (Endless Sky's inspiration and predecessor) there is a plug-in called ARPIA (and a follow-up, ARPIA2) which was, by all accounts, an awesome plug-in that added plenty of ships and outfits, a few systems and planets, and a lot of excellent story. Despite all of the great content, however, it clearly has a different feel to it, and renders some of the existing plotlines irrelevant. This question, as such, doesn't really have a hard yes/no answer, but is something you need to think about: How well does your content fit into the galaxy and the overall story? Does it add depth, complexity, and interest to the galaxy, or does it render parts of the existing game irrelevant? If your content doesn't fit nicely with the ES universe but it makes sense (or you prefer) to keep it in line with your artistic vision, then it is better as a plug-in. So, for the question: Does your content fit nicely within the ES universe?

7. Is your content "Safe For Work" / "Safe for General Audiences"? For vanilla content, keep in mind that ES is distributed globally, and subject to global rules and standards. As such, all content should be suitable for minors to read & play world-wide. So no gruesome torture, no graphic dismemberment, no steamy romance, no direct political statements, etc. If you want to make some of that, make a plug-in. I know there's at least one steamy romance plug-in out there, not sure about the others. As for the political statements, this is more along the lines of "______ is a terrible country!" or "__________ is the best political party." (with the blanks filled in with currently existing real-world countries, entities, or political parties.) As befits sci-fi, we should be exploring political and economic ramifications of interstellar travel and trade, and the pros and cons of different political, economic, and social structures. However, we also exist in the real world, and thus should take steps to avoid criticizing or promoting specific real-world entities.

If you can honestly answer "Yes" to every single one of these questions, then you can consider submitting a pull request to add your content to the vanilla game. If you answered "No" to any of them, please make a plug-in instead.

Lore

Now, some clarifications, particularly in regards to lore: All of the lore in Endless Sky is framed from the player's pilot's perspective. All of the ship descriptions, log entries, outfit descriptions, planetary descriptions, etc. are based on what the player's pilot knows. They learn this from missions and jobs, as well as from talking with their crew, people they meet, browsing info terminals, watching the news, and countless other sources of information that the player hasn't necessarily seen. As such, it is all considered to be "true to the best knowledge of the player's pilot." It is not guaranteed to be absolute fact. So something changing this lore is acceptable, so long as it fits into what might be the hard truth underlying it. Likewise, there are things like the ship description for the Heron. Given that the Heron never appears in a shipyard, and so far is never used in a mission, the player's pilot officially doesn't know that description. (I'd say that this is the case for all unique, uncapturable person ships: That no ship is "known" to the pilot until such time as they have officially seen one in a shipyard, captured one, or had the opportunity to interact with one in a mission. Until that point, these ships are just mysterious unique oddities of the galaxy.)

Unfortunately, we do not really have a "hard lore" to go by, so in a lot of cases it boils down to "can you make your case and convince the lead content creators & Devs that this is the way things are, or at least the way they should be going forward?" Everything really circles back to the fact that Endless Sky as a whole is a collaborative project, and everyone involved has to accept that there are a lot of people who have opinions about how things go, and will have a say in what happens.

Alongside this, you have almost assuredly noted that there are some people who seemed to have a significant say in what the lore is in the game. This influence basically stems from their contributions to the game and the general respect people have for their views on the game as a whole.

Likewise, we do have a few people who have significant say in particular regions. Typically, these are people who have invested a lot of work in a particular area will often be accorded a significant say in what happens in that area. To use corporate parlance, it could be said that these people are our "leads" in those areas: They don't have ownership over them, but it is recognized that they have the strongest overall vision for the area and are the ones putting the most work into expanding the story there. As such, it is courteous to take their views into account so as to not disrupt the plotlines that they are working on.

Plug-in versus Vanilla content PR:

Plug-in attributes:

• People have to choose to add it to their game.
• You have absolute control over everything in your plug-in.
• You retain absolute control over how the content of your plug-in is used. (legally, anyway)
• You are free to use any license you want for content that you create.
• You are free to break, modify, ignore, or follow whatever parts of existing lore suits your content.
• You have the freedom to pursue your own vision without any regard for anything in Endless Sky itself or the community in general.
• You can include content that doesn't meet the legal requirements for Endless Sky itself.
• You are free to include mature content.
• It is accessible to the entire player-base immediately instead of having to wait for a Dev to merge it and then for the next iteration of the release cycle.
• It can be distributed however you want. GitHub is the most common, but there are many mod distribution platforms out there, and many have at least a few ES plug-ins. You can even just email a zip file to someone.
• While you are working on it, your changes won't be accidentally overwritten or lost when your Endless Sky installation updates.

Vanilla attributes:

• Will be included in everyone's game as of the next appropriate iteration of the release cycle (odd version for content, even version for fixes/tweaks).
• Will be reviewed, proofread, edited, and commented on by the Devs and/or other content creators.
• Will be delayed until at least one of the Devs is satisfied that it meets their standards for inclusion.
• Might be vetoed by one of the Devs.
• May be edited, revised, altered, changed, or modified by others in the future through a similar process.
• Will only be distributed via official repositories (most commonly Steam and GitHub).
• Depending on how you do your work, there is a risk that you may lose things when you update your copy of the game.
• Will be distributed under a GPL 3+ (for text and code) or CC-BY-* for images. (The standard license used by most graphics in Endless Sky is CC-BY-SA-4.0, but there are some CC-BY and public domain, as well as both 3.0 and 4.0 versions)

Plug-in content can, and occasionally does, get pulled into vanilla. The most recent example of this is that the systems revealed in the Cognizance plot line are from a plug-in. One big problem with the PR process is that there's a very small pool of people doing reviews, and only 4 that can merge something. This means that getting content into vanilla (especially big things like mini-campaigns, new regions of space, etc.) can take a very long time. A plug-in, on the other hand, you could conceivably get into the hands of hundreds or even thousands of people quite quickly, and hopefully you could get feedback from more of them. Making a plug-in initially, then after play testing for a few months transferring into a PR with changes and polish is an excellent way of doing things, especially when starting out.

It is also worth noting that overall, the goal is to have vanilla Endless Sky be similar to Escape Velocity. EV is known for the fact that the vanilla game provides a large, diverse baseline galaxy, experience, and storyline, while a large and diverse plug-in community has expanded on that baseline in all directions. The third installment of that series has thousands of plug-ins, some of which are massive, complex, and almost worthy of being small games in and of themselves. It is our hope that, eventually, Endless Sky will have such a plug-in community as well. In other words, plug-ins aren't afterthoughts; they are intended to be a lively and every-day part of the end-user's gameplay experience - a part that lets people customize each game their own way. So the more plug-ins we have that provide more options, the better it is for the community.

Some example situations:

• If you want to add a station somewhere that looks like DS9, and has a shipyard where you can buy a variety of different Star Trek ships, then you should definitely do a plug-in.
• If you want to add a single ship that resembles a ship from another franchise as a person ship, named to allude to the ship in question, that players might see occasionally but never be able to fly, this could be a PR. (See the Lampyrid, for example: It looks very similar to the Firefly-class transport, but put them side-by-side it is clear that it is a similar ship, not a copy. Likewise, it has a name that alludes to the Firefly, but isn't exactly "Firefly" or "Serenity." This keeps Endless Sky safer.)
• If you want to reveal that the Republic is a dictatorship ruled by an evil wizard with the power to reshape reality and fire lightning bolts from his hands, this should probably be a plug-in.
• If you want to add a ship or outfit that vastly out performs everything currently in-game, then it should probably be a plug-in.

TLDR: My suggestion for those who feel that the decision of whether to make a PR or a plug-in is too hard, too complex, or just not a decision you want to make right now, my suggestion is thus: If in doubt, make a plug-in. It in no way restricts what you can do, and gives you the freedom to just make stuff according to your ideas. If, later on, it looks suitable for a PR, then you are always free to do so.

In other words, making a plug-in should be your default option, with submitting a pull request to bring it into vanilla an optional thing to pick later on.

When all is said and done, however, everyone creates content for their own reasons. Some find it relaxing, some find it enjoyable, others find it cathartic. No matter your reasons for creating content for Endless Sky, I hope that you continue to do so. The factors regarding whether something should be released as a plug-in or as a PR to vanilla are complicated, but the important part is that you make content. That's the point of content creation, right? I hope that this document has helped illustrated some of the advantages and disadvantages of each method of getting your content out there, and I hope to see your content soon.