Amazinite's Best Practices - TheGiraffe3/Endless-Sky-Creators-Handbook GitHub Wiki

ORIGINAL TEXT by Amazinite

Navigation

INTRO

GENERAL CONTENT GUIDELINES

STORY CONTENT GUIDELINES

GRAPHICS CREATION GUIDELINES

OTHER CONTENT GUIDELINES

INTRO

Hello there. I’m Amazinite, otherwise known as Derpy Horse on Discord and Steam. Since 2018 I have effectively been Endless Sky’s content lead, and over the years I’ve collected quite a list of unspoken guidelines when it comes to creating new content for the game, guidelines that I use to determine whether or not a pull request (PR) should be merged. This document seeks to outline all of these guidelines into a single publicly available place, as well as include best practice tips from myself and others when it comes to content creation. This public document should hopefully streamline the content creation process for everyone by giving existing or prospective content creators a sense of whether they’re on the right track while saving time by avoiding bad practices.

Note that some of these guidelines are very particular to me and my own ideas for the game’s direction; such guidelines will be marked justly. If at any point I’m no longer the effective content lead for the game, not all of these guidelines must necessarily remain. This document may also be updated with time as new guidelines are developed or deprecated, so check this document every so often to see if anything has changed.

For ease of reading, guidelines are divided into X sections, which are further divided into important subsections, and each paragraph also bolds sentences with the most important information.

GENERAL CONTENT GUIDELINES

Approach to Content Creation

Make content for yourself first before making content for the game: the main goal of creating content should be the enjoyment of yourself and others. Your work not being accepted into the base game doesn’t automatically equate to it being bad, and you should be willing to accept the possibility that what you create may work better as a plugin. Don't necessarily aim for vanilla on your very first go; keep the possibility of making your work a plugin open.

Any content that is created for the purpose of being a plugin can and maybe even should break the rules outlined in this document. Plugins allow you to experiment with the game’s mechanics and story in ways that the base game doesn’t cover. Don’t see these guidelines as guidelines for all content created for the game.

When aiming your content for inclusion in the base game, keep an open mindset with the shape that your content takes. It may be the case that your content does not fit with the base game in the exact shape that you first envisioned it; if you can be malleable with the shape that your content takes while working around the key concepts that make it yours, then with only a few tweaks, content that would otherwise not be considered fit for the base game can become fit.

Start small. Expertise is built through experience, and the review process can be easier if you first start with something small and learn on a small scale before going for something big. Starting with a massive project when you haven’t even gotten a single PR merged before runs the risk of disappointment if your massive project is deeply flawed in some way that you would have learned about had you started small.

Open large projects in chunks. Single large PRs can be difficult to review. If a large project can be broken up then it should be. By breaking large projects up into smaller pieces, each individual piece can be more easily reviewed, and some pieces can potentially be merged ahead of others, allowing at least some content from a large project to make it into the game once it’s passed the review process instead of holding up everything waiting on the last bit of content from the project to be reviewed.

Large PRs aren’t necessarily large in size alone; a PR can modify a large number of lines but be easy to review given what it’s changing (e.g. organizing existing content, adding to the map file, etc.). The important factors that signify a large project/PR that should be broken up into smaller chunks include (but are not limited to) a project that deals with a large number of concepts/areas of the game (e.g. a project that deals in multiple folders/area of the game may be able to be broken up to have one PR dealing with each folder/area) or a project that adds a large amount of content that doesn’t all necessarily rely on each other (e.g. given a string of 30 missions, each mission relies upon what came before it, but doesn’t rely upon what comes after it, so such a string of missions could potentially be broken in half to have 15 missions in one PR and 15 in another).

Respect the work and areas of others. Certain contributors have certain areas that they specialize in, and I'd like if said contributors were included in the discussion of any changes relating to their area. This does not mean that work cannot be done in these areas unless by these people, just that these people are essentially considered maintainers of these areas whose approval is appreciated (but not mandatory). The following is a list of areas of the game and the community members who specialize in them.

  • Coalition: Arachi-Lover
  • Ka'het: Beccabunny + Zitchas
  • Remnant + Ember Waste (generally): Zitchas

Github Etiquette

When you open a new pull request, you should always properly fill out the PR template that is provided to you. This includes erasing the sections of the template that you are not using while filling out the sections that you are. Do not simply leave the template blank or completely erase the template and put whatever you want. Do not erase the headers as they make finding specific information easier than without them. You may of course add new headers to the template as you see fit, but the basic information asked of you from the PR template should be filled out. The purpose of the template is to allow for easy reading of PR descriptions, so using the template helps those reviewing the PR.

New PRs should typically be complete products when opened, if not close to completion. This is so that review time can be spent on that content which is already ready to be merged, as opposed to people opening largely unfinished content and pulling review time away from other content which is more finished. If your content is unfinished and you’re posting it as a PR to get eyes on it then it should be posted as a draft with the expectation that you will finish it, but such unfinished PRs should still be nearly complete when they are opened. Unfinished “proof of concept” PRs are tolerable, but these may be better as issues rather than PRs. Unfinished content may also be better discussed on Discord rather than posting it to the game’s Github repository.

All pull requests should be opened as serious content intended to be merged. Do not open PRs just for the purposes of using the CI/CD tests or making them available in the launcher; this is abusing the system. Also do not open joke PRs that aren’t intended to be merged.

Be nice and help review other people’s content if you can. Almost as much as if not more development time goes into reviewing as compared to actually making the content. We want to ensure that any content that is merged into the game is of sufficiently high quality, and this is done through the review process. By reviewing the PRs of others, you help to cut down on the review time of maintainers who ultimately approve and merge PRs into the game, and you could also potentially spot an issue with a PR that no one else has, particularly when it comes to story PRs, as writing coherent stories without any plot holes or other narrative issues is no easy feat.

When you review a PR, go to the files changed tab to comment on specific lines of the PR. When you post a comment, click the “Start a review” button if you are planning on leaving more than one comment. When you bundle your comments into a review, the review comments display more cleanly on the conversations tab while also only sending out one notification for the entire review, whereas if you were to click “Add single comment” for every comment, they would appear messier on the conversations tab and each and every comment would be a new notification.

When addressing reviews to your PRs, here are some useful tips. Click the “Resolve comment” button on review comments that you have fully addressed, either through having made a change to address it or through having had a discussion about the comment. Use the “suggestion to batch” button when a review has made a number of suggestions; this button becomes available when looking at comments from the “Files changed” tab of your PR.

Remember that we’re all here to make the game better. No one is here to intentionally make the game worse. So even if you disagree with someone’s content proposal, do not attack them for it. Instead, politely state why it is that you disagree with the content proposal, and perhaps explain how it might be changed to be made better in your eyes. And in the end, realize that even if you disagree with one small change that gets merged, this is a vast game with many moving parts, and no one change will ruin the whole game, especially as anything could change with the game in the future.

My Review Process

A list of review concepts specific to how I go about things. Not necessarily how everyone needs to review.

Various principles of reviewing I go by:

  • Minimum necessary change.
  • Gameplay over reality vs don't break immersion.
  • Simplicity over complexity vs reduce code duplication.
  • No half-measures; put forward the best work you can.
  • Importance of readability (and how readability and complexity don't necessarily run counter to one another).

I’m easily distracted. If I say I have a schedule for what I’m going to work on next you’d best bet against it. I basically just hop around all the open PRs and review whatever I feel like at the time, although I do have a preference to getting to the newest and oldest stuff.

I’m very open to working with content creators to polish up their PRs before merging. It’s incredibly rare that PRs of any substantial size have nothing wrong with them. There’s almost always a way in which a PR could be improved; perhaps the story isn’t quite right or the dialog falls flat or doesn’t match the situation. And given the years of working on the game, it may be that I ask for something outside of your experience level, or I simply ask for a fairly substantial change, in which case I’ll be willing to provide my own time to put in the work to make the changes I’d like to see.

Assets

No NC (No Credit) assets.

STORY CONTENT GUIDELINES

Important to All Story

The player is not the center of the universe. Player actions/choices won’t change the world in illogical ways and some story constants will always occur. An example of the world changing in an illogical way is if the side of the campaign the player sided with changed the facts of how events came to be. (Example: no matter the side the player chooses, the Syndicate will always have obtained the Oracle from the Alphas and followed its predictions to start the war.) More info here.

Ask what story you want to tell. Try to keep it to a single sentence. Realize that a single sentence story can be told in a multitude of ways. (Can still have other sentences that describe your story, but try to form a hierarchy of what you think is important.) For example, the single sentence story of the Bactrian unlock missions would be “Gain the trust of the Deep so that they allow you to buy Bactrians.” How that trust is gained could have been done in any number of ways.

Writing Mission Conversations

Don’t stick defer points way down in your conversations.

Avoid empty choices, e.g. choices that are just (Continue.) This is a video game, not a novel.

Action choices should be in first person.

Every line gets an extra tab within the backticks, except for the very first line in the conversation. A common mistake is to forget extra tabs all together or to not put tabs after paragraphs that follow choices.

New Alien Factions

Minimum requirements for a new faction:

  • General story idea.
  • At least a first contact mission.
  • Finished ship and outfit graphics.
  • Finished systems and planets. (No minimum number of systems or planets necessary so long as the story backs up why they have the number they do.)

Avoid turning Endless Sky into Dragon Ball Z. Every new alien faction or weapon or ship doesn’t need to simply be a more powerful version of what came before it.

Think of alien factions as a set of concepts to explore; don't repeat concepts, at least not too often. Ideas are a dime a dozen, so if your idea isn't unique from within the existing world of Endless Sky then it's highly unlikely to be accepted.

My Personal Story Takes

Stay within the Milky Way. I'm of the position that the story of Endless Sky is or at least should be a story of the Milky Way and the species within it. I don't want to be introducing other galaxies into the mix, especially when we haven't even finished with the first one.

Don't add new systems near the Deep (near being within jump range). I've put forward the idea that the Deep is/was isolated in more ways than just from humanity, but from the rest of the galaxy in general. There's only one way in and out of the Deep regardless of whether you have a hyperdrive or a jump drive, and I'd say that's very much intentional on the part of the Pug and should remain that way with any new content that gets added.

Off Limits

(Smut) There aren’t really any story topics that are strictly off limits on their face, but there is a certain degree of tastefulness with the game’s story that we want to maintain. When dealing with certain sensitive topics, it may not be prudent to be overt with them. Idk, someone’ll probably try to push the boundary at some point and we’ll have something here, but I’d rather make rules about that type of stuff when people actually try to do it as opposed to trying to brainstorm stuff beforehand that no one may even try.

GRAPHICS CREATION GUIDELINES

Use the same tools; shared tools make work for everyone easier. We use Blender for creating 3D models that we export to PNGs and GIMP for post processing said PNGs and other graphics such as effects. Inkscape is also sometimes used for the creation of graphics such as the map labels or licenses. Notepad++, while not mandatory since there are loads of .txt editors, is highly recommended for new content creators who don’t already have a decent text editor they like to use. Also VSCode or something, idk, someone else tell me what they use.

Use the templates when creating new ships or outfits in Blender.

OTHER CONTENT GUIDELINES

Shut up about realism in ship, weapon, and outfit balance.

Shut up about realism in time tables.

Shut up about realism in technological advancement.

No, I don't want to expand the Milky Way. I'm not outside of the possibility of doing so in the future, but for now I'd much rather use the existing empty space that we already have before considering expanding the galaxy.

Sometimes you have to dig wide before you can dig deep. If you dig a hole too deep then the walls will collapse in on you.

IMPORTANT: The contents of this page are the expressions of somebody else and cannot be claimed as my own. Minor adjustments have been made to formatting for ease of readability, however no information has been omitted from the original text.