Create CreatingFormations.md #176

chemtrailoperator · 2025-10-20T20:22:58Z

(Choose one heading.)

New feature

(If this PR is to include details on a new feature or a change to a feature, include a link to the PR that makes the corresponding change to Endless Sky.)
endless-sky/endless-sky#4471

Summary

Created a new wiki document called CreatingFormations to cover coding formations into the game. Written by reverse engineering syntax in formations.txt

TheGiraffe3

Could you add links to this page in Home.md and _Sidebar.md?

wiki/CreatingFormations.md

typo fix Co-authored-by: Loymdayddaud <[email protected]>

chemtrailoperator · 2025-10-21T13:21:45Z

Could you add links to this page in Home.md and _Sidebar.md?

Done.

TheGiraffe3 · 2025-10-21T14:17:24Z

Ideally that would be done in this PR, since this is where the file is added.

warp-core · 2025-10-21T15:04:04Z

I'm guessing you're using GitHub's web editor to make these changes.
To add additional changes to this PR:

Navigate to the "head" branch. The easiest way to do this is to look near the top of this page, just below the pull request title, and click the link with the text: "chemtrailoperator:master" (the link in this message will also work).
This should take you to the main page for your fork of this repository, on the appropriate branch for this PR.
Navigate to the file you want to edit.
Use the edit button, make your changes, then click the "commit changes" button.
This should add a new commit to the branch for this PR.

Once a file is changed by a PR, making further changes to it is a bit more straightforward, you can find a guide here: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#making-changes-to-files-in-your-pull-request

If you are using git or GitHub Desktop on your computer, you can alternatively either merge the branches with the other commits into this one, or cherry-pick those commits onto this branch.

chemtrailoperator · 2025-10-21T15:11:31Z

I'm guessing you're using GitHub's web editor to make these changes. To add additional changes to this PR:
1. Navigate to the "head" branch. The easiest way to do this is to look near the top of this page, just below the pull request title, and click the link with the text: "[chemtrailoperator:master](https://github.com/chemtrailoperator/endless-sky-wiki/tree/master)" (the link in this message will also work).

2. This should take you to the main page for your fork of this repository, on the appropriate branch for this PR.

3. Navigate to the file you want to edit.

4. Use the edit button, make your changes, then click the "commit changes" button.

5. This should add a new commit to the branch for this PR.
Once a file is changed by a PR, making further changes to it is a bit more straightforward, you can find a guide here: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request#making-changes-to-files-in-your-pull-request

If you are using git or GitHub Desktop on your computer, you can alternatively either merge the branches with the other commits into this one, or cherry-pick those commits onto this branch.

Apologies, I am very new at using Github.
I made two new pull requests for the changes to the files. Do those need to be closed?

TheGiraffe3 · 2025-10-21T15:17:32Z

Yes.

chemtrailoperator · 2025-10-23T12:51:19Z

done

petervdmeer

Thanks for documenting this!

I added some remarks based on the implementation and the early/original RFCs.

petervdmeer · 2026-01-18T18:46:34Z

wiki/CreatingFormations.md

+
+`rotatable` specifies a degree of rotational symmetry for the formation, such as 90 for squares, and 1 for circles.
+
+Both attributes essentially add reference directions for the formation, from only one pointing out the nose to any axis or multiple of degrees thereof.


The flippable attribute does not add directions, but allows formations patterns to mirror themselves over an axis if the flagship suddenly changes direction. (For example by revere thrusting.)

petervdmeer · 2026-01-18T18:50:29Z

wiki/CreatingFormations.md

+```
+Will render the first position at 0,200 and then 0,400; 0,600; etc.
+
+If no repeat attribute is present, all positions will be filled, and any remaining ships will group at 0,0 underneath the flagship.


This description for "remaining ships at 0.0" is correct for the current implementation, but do we want this? We might want to consider such "remaining ships" behavior to be undesirable, and file a feature request to let those ships beyond the end position return to the default "flocking" behavior. What do you think?

petervdmeer · 2026-01-18T18:52:03Z

wiki/CreatingFormations.md

+		repeat
+			...
+```
+`arc` populates an arc around the player.


Around the flagship of the formation. (Formations can also be applied to NPC ships.)

petervdmeer · 2026-01-18T18:57:19Z

wiki/CreatingFormations.md

+	flippable x y
+	rotatable <degree of symmetry>
+	arc
+		start <x> <y>


An arc also has an anchor point (which defaults to 0,0 relative to the ship around which the formation is formed).

petervdmeer · 2026-01-18T19:12:55Z

wiki/CreatingFormations.md

+
+Blocks can be one of three types: `arc`, `line`, and `position`.
+
+<degrees> are clockwise


positive degrees are clockwise, negative degrees are counter-clockwise.

petervdmeer · 2026-01-18T19:28:14Z

wiki/CreatingFormations.md

+		...
+```
+
+To make formations scalable to any number of ships, a repeat attribute must be applied to the block. Any attribute that exists in a block can be used as a child attribute in `repeat`.


I think it would be nice to describe that the attributes in repeat are added on top of the original values, so repeating with a position of 1 will make each repeat iteration one larger than the previous one. While repeating an arc with an non-zero angle in the repeat section will make the repeat sections have larger angles.

petervdmeer · 2026-01-18T19:33:42Z

wiki/CreatingFormations.md

+
+# Symmetry
+
+If a formation is symmetrical, the definition can include an axis or degree of symmetry. In the event of escorts losing their formation, such as when the flagship rotates faster than the escorts can move, they will re-establish the formation referenced from the nose or one of the symmetry directions, whichever is closer.


The formation is relative to the flagships movement direction, not to the flagships rotation. (Except when the flagship is not moving at all, then it is relative to its rotation.)

Create CreatingFormations.md

a120aaa

TheGiraffe3 added the enhancement Adding documentation about a new feature being PR'd to endless-sky/endless-sky label Oct 21, 2025

TheGiraffe3 reviewed Oct 21, 2025

View reviewed changes

wiki/CreatingFormations.md Outdated Show resolved Hide resolved

wiki/CreatingFormations.md Outdated Show resolved Hide resolved

wiki/CreatingFormations.md Outdated Show resolved Hide resolved

chemtrailoperator and others added 3 commits October 21, 2025 08:12

Update wiki/CreatingFormations.md

952f180

typo fix Co-authored-by: Loymdayddaud <[email protected]>

Update wiki/CreatingFormations.md

35e4d32

typo fix Co-authored-by: Loymdayddaud <[email protected]>

Update wiki/CreatingFormations.md

198bf38

typo fix Co-authored-by: Loymdayddaud <[email protected]>

chemtrailoperator added 2 commits October 21, 2025 10:13

Add link to Creating formations in sidebar

40a6134

Add link to 'Creating formations' in Home.md

f5c1c72

TheGiraffe3 requested a review from warp-core December 16, 2025 09:13

petervdmeer reviewed Jan 18, 2026

View reviewed changes


		`rotatable` specifies a degree of rotational symmetry for the formation, such as 90 for squares, and 1 for circles.

		Both attributes essentially add reference directions for the formation, from only one pointing out the nose to any axis or multiple of degrees thereof.


		Blocks can be one of three types: `arc`, `line`, and `position`.

		<degrees> are clockwise


		# Symmetry

		If a formation is symmetrical, the definition can include an axis or degree of symmetry. In the event of escorts losing their formation, such as when the flagship rotates faster than the escorts can move, they will re-establish the formation referenced from the nose or one of the symmetry directions, whichever is closer.

Create CreatingFormations.md #176

Are you sure you want to change the base?

Create CreatingFormations.md #176

Uh oh!

Conversation

chemtrailoperator commented Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Uh oh!

TheGiraffe3 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chemtrailoperator commented Oct 21, 2025

Uh oh!

TheGiraffe3 commented Oct 21, 2025

Uh oh!

warp-core commented Oct 21, 2025

Uh oh!

chemtrailoperator commented Oct 21, 2025

Uh oh!

TheGiraffe3 commented Oct 21, 2025

Uh oh!

chemtrailoperator commented Oct 23, 2025

Uh oh!

petervdmeer left a comment

Choose a reason for hiding this comment

Uh oh!

petervdmeer Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

petervdmeer Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

petervdmeer Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

petervdmeer Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

petervdmeer Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

petervdmeer Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

petervdmeer Jan 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

chemtrailoperator commented Oct 20, 2025 •

edited

Loading