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

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 to 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 or the other. Now, let's get started. (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 packaging all or part of the content into a commercial game and selling it for profit (so long as all contributors are attributed in the credits, 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 only (currently) four people with authority to commit changes into the base game. We often call these people the "Developers" (or "Devs"), and they have the final authority over what gets in and what doesn't. Other than the Devs, there are over 150 people who have submitted code and content to Endless Sky. As a collaborative project, ES is open for anyone to propose changes, edits, revisions, modifications, replacements, and 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 final say or 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, characters, and stories from other science fiction universes. While Easter eggs are acceptable (and even fun!), they can be legally touchy. As a minimal criterion for inclusion in ES, all material must meet the legal copyright framework of the game. In layman's terms, this usually means that everything you submit in a PR must be either your own creation or something that you have legal permission to edit and distribute. This means that you cannot simply pull a model, character, or text directly from another source, render it, and submit it for inclusion in Endless Sky; instead, you must make a new model yourself (or get someone else to for you). Can you attest that all your material is either of your own creation or material that can be legally distributed under the GPL 3 license?

6. Some people have ideas for content that is awesome, but doesn't necessarily fit well into the established Endless Sky universe. As an example, there is a plug-in for the Escape Velocity franchise (Endless Sky's inspiration and predecessor) called ARPIA (and a follow-up, ARPIA2) which was, by all accounts, an awesome add-on that added many new ships and outfits, a few systems and planets, and a lot of excellent story. Despite all of this 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 (essentially or effectively) irrelevant? If your content doesn't fit nicely into the existing 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.

7. Is your content "Safe For Work" / "Safe for General Audiences"? For vanilla content, keep in mind that Endless Sky is distributed globally, and is subject to global rules and standards. As such, all content should be suitable for minors to read & play world-wide. This means: No gruesome torture, no graphic dismemberment, no steamy romance, no direct political statements, and so on. If you want to make such content, make a plug-in. I know that there's at least one steamy romance plug-in out there, though I'm not sure about the others. As for political content, 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 science fiction, 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 may 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.

Some clarifications are in order, particularly in regards to lore: All of the lore in Endless Sky is framed from the perspective of the player's pilot (referred to below as "the pilot"). All of the ship descriptions, log entries, outfit descriptions, planetary descriptions, etc. are based on what the pilot knows. The pilot learns this from missions and jobs, as well as from talking with their crew and 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 pilot." It is not guaranteed to be absolute fact. This means that changing this lore is acceptable, as long as it fits into what might be the hard truth underlying it. As a specific example, take the ship description of the Heron. Given that the Heron never appears in a shipyard, and so far is never used in a mission, the pilot officially doesn't know any of the information contained in its description. This is likely to be the case for all unique, uncapturable ships (including the so-called "person" ships); that is, no ship is "known" to the pilot until 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 and unique oddities of the galaxy.)

Unfortunately, there isn't really any "hard lore" or a "show bible" that we can reference, so in a lot of cases it boils down to whether or not you can make your case and convince the lead content creators and 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 most likely noted that there are some people who seemed to have a more significant say in what goes into the game's lore. This influence stems from their significant and often voluminous contributions to the game, as well as the general respect that people have for their views on the game as a whole.

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

Pros and cons of plug-ins versus vanilla content PRs: Plug-ins:

• Must be deliberately added to the game by each individual player.
• Are under the absolute control of the author, in terms of content and licensing.
• May be licensed however the author wishes.
• May freely follow, ignore, modify, or even break any part of the game and its lore.
• May freely pursue the author's own vision, without any consideration or regard for anything in Endless Sky or the greater community.
• May include content that does not meet the legal requirements of Endless Sky.
• May include content that is mature or otherwise not "safe for work".
• Is immediately accessible to the entire player-base.
• May be distributed however the author wishes or is able. (GitHub is the most common method, but there are many mod distribution platforms, many of which already have at least a few ES plug-ins. The author can even simply distribute a zip file directly to the target audience, via email or any other method.)
• Is safe against being overwritten by game updates.

Vanilla content PRs:

• Are distributed equally to every player as part of the next appropriate release cycle iteration (odd version numbers provide content updates, even version numbers provide fixes and tweaks).
• Will be reviewed, proofread, edited, and commented upon by the Devs and/or other content creators.
• Will be delayed until at least one Dev is satisfied that it meets their standards for inclusion.
• May be vetoed by any one of the Devs.
• May be edited, revised, altered, changed, or otherwise modified by any other future contributor through similar processes.
• Will only be distributed via official repositories (currently GitHub and Steam).
• May be vulnerable to being overwritten by game updates, depending upon how the author structures their workspace.
• Will be licensed and distributed under either the GPL 3+ (for code and text) or CC-BY-SA-4.0 (for artwork and images).

Content from plug-ins can, and occasionally does, get pulled into the core game. One recent example of this is the systems revealed during the Cognizance plotline. One major issue with the PR process is that there is a very small pool of people doing reviews, and only four of those people can perform the final merge. This means that getting content into vanilla (especially big things like campaigns and new regions of space) can take a very long time. A plug-in, on the other hand, could conceivably reach the hands of hundreds or even thousands of people quite quickly, more of whom would hopefully begin providing feedback. An excellent way of releasing new content, especially if you are just starting out, would be to make a plug-in at first, and only turning it into a PR after you and/or others have play-tested for a few months, making sure to include any changes and polish acquired along the way.

It is also worth noting that overall, the goal of the Endless Sky project is to reach a similar state as the original Escape Velocity games. EV is known for the fact that the vanilla game provides a large, diverse baseline galaxy, experience, and storyline, while an even larger and more diverse plug-in community has expanded on that baseline in all directions. The third installment of that series, Escape Velocity Nova, currently has thousands of plug-ins, some of which are massive, complex, and sometimes worthy of being small games in their own right. It is our hope that eventually, Endless Sky will have such a plug-in community as well. In other words, plug-ins are not an afterthought; 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. The more plug-ins we have, and the more options those plug-ins provide, the better it is for the community.

Some example situations:

• If you wanted to add a station somewhere that looks like DS9, and has a shipyard where you can buy a variety of different Star Trek ships, you would definitely create a plug-in.
• If you wanted to add a single "person" ship that resembles a ship from another franchise, and is named to allude to said ship, you could create a PR. (See the Lampyrid for an example: Although it looks very similar to the Firefly-class transport, if you put them side-by-side it is clear that it is merely a similar ship, not a copy. Likewise, its name alludes to the Firefly, but isn't exactly "Firefly" or "Serenity". This helps keeps Endless Sky safe from legal repercussions.)
• If you wanted to reveal that the Republic is a dictatorship rule by an evil wizard with the power to reshape reality and fire lightning bolts from his hands, you would almost certainly create a plug-in.
• If you wanted to add a ship or outfit that vastly out performs everything currently in-game, you should probably create a plug-in.

TL;DR: For those of you 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: When in doubt, make a plug-in. This in no way restricts what you can do, and gives you the freedom to 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, and submitting a pull request to bring it into vanilla can be an option for later, if you so desire.

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.