PioneerWiki - User contributions [en]

Places of interest

2024-08-23T02:27:41Z

Sturnclaw:

If you've found something bizarre and/or wonderful, let other players know where here. Though if it's a bug it should be on the [https://github.com/pioneerspacesim/pioneer/issues Issue tracker.]

Note that many of these discoveries are out-of-date or perhaps no longer existing as the results of procedural generation change with fixes and improvements. Many of these discoveries still exist in the universe, but simply somewhere else, waiting for an intrepid explorer to find them again and document them.

'''Timing (Eclipses, etc.)'''

*Epsilon Eridani (1,-1,-1), New Hope, Itzalean space port, at January 1 3200 22:00 there is an eclipse as Hades blocks out the light from Epsilon Eridani.
*Go to Vetiar (-14, -12, -11) A's colony Brennan Base on the world Morales's Mine and wait until 3204 Apr 25 around 2:53. A double sunset awaits.
*Canen (-89,0,1), Valášek Colony, Fort Robinson: 3208, July 10th, 19:24:52, the medium gas giant Canen b's decent-sized rings partially eclipse the red giant Canen through the oxygen atmosphere of Valášek Colony.
*Zelia (-16, -3, 1), 11 June 3201, at around 19:30 go stay near the sunny side of Zelia A,B e and you will see a merged 8-shaped shadow of it's two moons.
*Canack(-3127, 0, 2), 16 January 3200, land on asteroid Canack a a, around coordinates S 005°12'49" W 152°14'22". At around 4:20, the brown dwarf Canack a will block the red hypergiant Canack. The exact time and place provided is not a must, as this star-star eclipse is a regular occurence due to Canack a and Canack a a having similar orbital planes relative to Canack.

'''Vastness'''

*Waioeth (-13, -9, -13) is a red supergiant roughly 1.7 AU wide. At the distant world of Fox Colony, one can buy basic military drives, hyperspace cloud analyzers, and a variety of other interesting sundries. A heck of a vacation spot.
*Ackay (-13, -13, -10), a red giant star 0.15 wide. The planets are far enough away from each other to make missions between them completely impractical. A superjupiter as far away as Pluto!
*Ethandce (-32, -36, 0) is a triple star system formed by hypergiant and supergiants. In addition, two of these stars (Ethandce A and Ethandce B) are very close to each other.

'''Life, But Not As We Know It'''

*Gretia (-7, -6, -8)'s world Sampson looks like a partially terraformed Mars. Its ecosystem is reputedly quite complex, and the planet is studded with human settlements. Not exactly undiscovered country, but if all you want is to see an exotic lifeform in its natural habitat, and you don't ''really'' want to just get away from it all, it's a great place to start. You'll also get a look at life under an M class star!

'''Terrain Features'''

*In Edack (4, -2, 0) system, on Espinoza's Rock (the innermost planet), near Foley City; there is a very interesting canyon with bizzare pillar-like structures.

 '''Man Made'''

*Olsina's Rock, the innermost planet in Gliese 205 (2, -1, -1) has 20 space stations orbiting it.

'''Galactic Center'''

*Sagittarius A* (-3125, 0, 0) system houses the galactic anchor; a supermassive black hole which keeps the Milky Way Galaxy together with it's strong gravity. The system also houses 2 terrestrial bodies and 3 orbital stations.
*Terminus, a planet in the Sagittarius A* (-3125, 0, 0) system rotates so fast that it's surface's tagential speed exceeds the escape velocity of the planet; ships have to accelerate towards the ground in order to land!
*Having no stars in the system, it can be quite hard to see ships and planets since there are no natural light sources.

'''Sol System'''
Travel to Thebe's vicinity at the Sol System (0, 0, 0) right when game starts (recommended to start at Mars). If you did it correctly, you will see Jupiter about to block out Sol's light! (Note that Thebe is a moon of Jupiter and you can always try again because of it's proximity to the planet). Speed time up to 100x real time and enjoy the eclipse!

Manual

2023-09-15T03:27:51Z

Sturnclaw:

Pioneer is a space adventure game set in the Milky-way galaxy at the turn of the 31st century. The game is open-ended, and you are free to explore the millions of star systems in the game. You can land on planets, slingshot past gas giants, and burn yourself to a crisp flying between binary star systems.

This reference manual provides a brief overview of the game.

This manual is a good bit out of date, but is slowly being improved.

== Main menu ==
[[File:00_main_menu.png|right|600px]]
* '''Quick Load''': Loads the game you saved using quick save (ctrl+F9)
* '''Start at Earth''': You start the game in the Solar system, on Earth, at London Spaceport with an outfitted [[Sinonatrix]]. It can be considered an easy start. Sol is the capital of the Solar Federation
* '''Start at New Hope''': You start in Epsilon Eridani, the capital of the Commonwealth of Independend Worlds. Your [[Pumpkinseed]] stands on Itzalean Spaceport on New Hope. This is a bit more difficult starting point than Earth. Itzalean is in an area of frequent solar eclipses.
* '''Start at Barnard's Star''': You start on the dock of High Security Prison Tranquility, orbiting Barnard's Star, not far from Sol. You have a poorly outfitted [[Xylophis]], so you can consider it a difficult start.
* '''Load Game''': You can load previously saved games here. Saves created with older versions of Pioneer might not load. This usually happens when some major thing changes in the game.
* '''Options''': you can access Pioneer's [[Settings Menu]]. You can set up graphics, controls, volumes or language for example.
* '''Quit''': Exit the game.
* '''Build''': this number is the build of the game you are running. Basically a version number, useful for reporting bugs for example.

==Flight==
Flight physics in Pioneer is Newtonian, which means there's no arbitrary limit to speed, orientation or position. The ships don't slow down in space, until it actively thrusts in the opposite direction it's flying. Or hits something. Ship acceleration depends on ship mass and engine thrust.
Speed only have a meaning relative to something, so you have to pick a point of reference. This is automatic, based on the distance to the bodies. You can reach very high speeds compared to what we are used to here on the face of a planet. On the magnitude of thousands of km/s.

There's an aided flight mode which compensates for the drifting in the vacuum of space, called Set Speed mode. It tries to maintain a set speed to the direction the ship is facing, using the maneuvering thrusters. The performance of this aid varies ship to ship, and the cargo load could also have an impact on it.

Ships in the game are quite powerful in terms of acceleration, cargo and delta-v capacity compared to real spacecrafts. It's entirely possible to travel to the edge of a star system even with the smallest shuttle. It will just take significantly more time.

Gravity is simulated on a two-body level. You can orbit any planet or moon, but only the closest body's gravity affects your ship. This is the same body you measure your speed to. This also means that you have to take the planets gravity into account when you are flying close to it, landing, or taking off. You can also use this to your advantage to alter your course using less fuel for example.
Distances are realistic, so space travel can take several days or even weeks in a large system. Time could be accelerated up to 10000 times to shorten travel for the player. This doesn't correspond with any device or technology in the game universe though. It's just a UI/Gameplay feature.

=== Flight UI ===

Beginners are strongly recommended a look at the [http://pioneerwiki.com/wiki/Basic_flight Basic flight] article, to learn how to control the ship.

When you pick your starting point, you will get behind the controls of your ship. [[File:Manual flight ui 01.png|right|600px|Manual flight ui 01.png]] There are several things on the flight UI:

*'''Prograde marker:''' The direction you are flying relative to the point of reference,
*'''Speed relative to reference body''': The speed of the ship relative to the point of reference (''"System"'' in this example).
*'''Prograde marker & speed (target)''': Direction and speed of the ship relative to the target (which itself moves around a star for example)
*'''Heading''': Only shown, top centre of screen, when close to planet (not shown in screen shot here). Can switch reference system by clicking it to be either in planetary coordinates, heading 0 = north, 90 = east, 180 = south, 270 = west; or in system-wide coordinates, heading is on the celestial sphere (defined by the ecliptic)
*'''Pitch''': Only shown, at right centre of screen, when close to planet (not shown in screen shot here). Shows elevation of ship direction over horizon.
*'''Target''': The navigation target, selectable by using the Left Mouse Button. You can set any body or ship as the point of reference with Ctrl+Left Mouse
**'''Distance to target''': Shows the distance to the selected object. The unit is km for shorter distances and AU for large.
*'''Speed lines''': A visual aid showing the direction and speed of motion.
*'''Fuel reserve''': The % amount of fuel (propellant really) the tanks contain. You can refill it during flight using the Info View screen (F3). Spaceports do not refil your tanks automatically, but you can do it on the station lobby. Note that it only shows %, but your actual deltaV can be more since you continuously expel propellant, so your craft becomes lighter.
*'''Scanner''': Scanner display which shows nearby contacts. Only works if the ship has a Scanner equipped. This area also shows any messages you receive, like completion or failure of a mission for example.
*'''Dashboard:'''
Note: Parts of this section are outdated because of the ongoing UI rewrite.
**'''Date, Time and time acceleration controls''': [[File:Manual flight ui 02 time.png|RTENOTITLE]]
***Shows the current date and time.
***The Pause, Play, and Fast Forward buttons can be used to speed up time to shorten long trips. Or to wait for better missions or ships on a station. Maximum level of time acceleration might be restricted, especially in the vicinity of stations or planets.
***This restriction could be overridden by holding ctrl when activating it. Use this with caution, because it could easily wreck your ship.
**'''Screens''': [[File:Manual flight ui 03 screens.png|RTENOTITLE]]
***These buttons provide access to certain screens like Info View or Maps. You can also use the corresponding F-keys to access them. From left to right:
***'''View''' (F1): Switches between internal and external views. You can switch back to these views from any other screen using this button or key.
***'''Maps''' (F2): Sector and System Map and System information screens. You can plan your trip here.
***'''Info''' (F3): Information screens, about the ship, the player, missions, cargo and crew.
***'''Comms, Station screen''' (F4): Opens Station Screen while docked to a spaceport.
****There are six attitude (ship facing) options meant for orbital operations:
*****Prograde/retrograde: faces the ship in/opposite the direction that you are traveling (changes the height of the orbit)
*****Normal/anti-normal: faces the ship in the direction [anti-]normal to your orbital plane (changes the orbit inclination)
*****Radially in/radially out: faces the ship toward/away from the orbited body
****If the ship has an autopilot installed, there are also options for automatically flying the ship into a low/medium/high orbit, flying to the vicinity of the navigation target, and flying to the navigation target and docking.
**'''Controls''': [[File:Manual flight ui 04 controls.png|RTENOTITLE]]
***These are flight related controls, corresponding F-keys could be used also.
***'''Flight Mode''' (F5): Switches between ''Set Speed'' and ''Manual'' flight mode. Also switches off the autopilot or could be used to undock or take off.
***'''Landing gear''' (F6): Rises or lowers the landing gear (undercarriage).
***'''Hyperdrive''' (F7): Engages hyperdrive. Needs a reachable hyperspace target selected on the Sector Map, and enough fuel for the trip. If it is crossed out, then you are in the hyperperspace limit zone, and jumping is illegal. You need to fly far enough from the station, or the police will chase you down.
***'''Low Thrust''' (F8): Sets the percentage of low thrust (Thrusting while holding Left Shift)
***It also displays the desired speed in Set Speed flight mode. On this image it shows the flight mode, which is set to manual.
***The small '''circular button''' next to the flight mode display show the status of the rotation damping.
***The '''[!]''' next to the rotation damping indicator shows your alert status.
***[[File:Manual flight ui 05 controls.png|RTENOTITLE]] These are controls for Scanner mode, Missiles and equipment (ECM) and Messages respectively.

===Combat===
Combat in Pioneer is quite straightforward right now. You can buy Pulse cannons or Plasma accelerators of different power and fire rate, if your ship has mount for them. Some ships have a rear mount too. Cannons generate heat when fired, and they need some time to cool down. They can not be fired if they are overheating.

You can also buy several types of missiles, which can be fired using the '''M''' key, if you have a combat target. An ECM can provide protection against missiles by overloading their guidance.

You can target any ship as combat target, using your '''Left Mouse Button'''(which doesn't change the Navigation target). The ship's computer displays the speed of the ship relative to your vessel, and it's distance. There's also a lead indicator, a little cross which shows the predicted location of the target. This is the spot where the ship will be in theory based on it's speed and direction, when the projectiles reach that distance. It's harder than that though, since no sane enemy will fly in a straight line at a constant speed. You shouldn't do that either, and this is where your maneuvering thrusters can be very useful.

Ship durability is determined by it's hull's mass. Lighter ships can take less damage, but they are more maneuverable generally, then a behemoth transport, which might withstand sever punishing before giving in. You can repair any damage you suffer on spaceports, but it will cost you.

There are several additional equipment that can increase your chances in a firefight (and make your life harder if your opponent has them):
* '''ECM''': Electronic countermeasure against missiles. The Advanced ECM provides protection against more sophisticated missiles.
* '''Hull Auto-repair system''': As the name implies, it slowly repairs any damage your ship took. It weights 40t, so smaller ships can not have it.
* '''Hypercloud Analyzer''': You can get readings from a hyperspace cloud remnant, like destination and arrival date. It's useful if you need to follow somebody.
* '''Laser Cooling Booster''': Speeds up the cooling of cannons, so continuous firing can be maintained longer.
* '''Scanner''': A sensor system that shows the ships and objects around you. A form of radar basically.
* '''Radar Mapper''': Provides additional information about the combat target, like the type of ship, mass, condition among others.
* '''Shield Generator''': Projects a protective screen around your ship, which can take a certain amount of damage before collapsing. It recharges slowly over time. You can mount several Shield Generator to increase its power.
* '''Shield Energy Booster''': Increases the effectiveness of the shields.

===Flight controls ===
A brief summary of flight controls. A more detailed list can be found at [[Keyboard and mouse controls]].

*'''Orientation''':
** '''W, S''': Pitch
** '''A, D''': Yaw
** '''Q, E''': Roll
** '''P''': Kill rotation
** '''R''': toggle rotation damping
** '''Right mouse button''': hold to activate mouse control
*'''Movement''':
** '''I, K''': Forward and backward thrust
** '''J, L''': Side thrust
** '''U, O''': Up and down thrust
* '''Left Shift''': use lower thrust
* '''F8''' : Set low thrust percentage

*'''F5''': change flight mode, or undock, takeoff
** '''Manual flight''': everything is manual
** '''Set Speed Mode''': the ship tries to maintain the set speed in the direction the ship is looking. Using the thrusters override it temporarily
***'''Return''': Increase speed
*** '''Right Shift''': Decrease speed
*'''F6''': toggle landing gear
*'''F7''': Engage hyperdrive
*'''Weapons''':
** '''Space''': Fire cannon
** '''M''': Fire missile
*'''View''':
**'''F1''': Cycles trough internal, external and sideral views. External rotates with your ship, sideral doesn't.
**'''Numpad 2 4 6 8 and 1 3''': Rotate the the external views.
**'''Numapad + -''': Zoom external views.
**'''Numpad /''': Reset view.
**'''Internal views''':
***'''8 2''': Front and rear view. You can shot backwards in rear view if you have a weapon installed on that mount.
***'''4 6''': Left and right view.
***'''9 3''': Top and bottom view.

==Map (F2)==
This is where navigation takes place. You can open the Map view with the F2 key or the button on the dashboard.
[[File:Manual_map_buttons.png|left]]
There are several maps you can use. You can reach them by using their F-key, or the button on the right side of the dashboard. If you come back to the map view you will return to the map screen you were at when you switched to another view. Orbital Map and System info shows the information of the system which is selected on the Sector map.
===Sector Map (F5)===
[[File:Manual_map_sector_01.png|right|600px]]
[[File:Manual_map_sector_02.png|right|600px]]

The sector map shows the star systems in the galaxy, and you can plot your hyperspace route here, or you can just hunt for interesting systems for later visits. Every system is indicated by a sphere. Its colour indicates the primary star type. You can select a system by clicking on it. If it's a system with multiple stars, you can cycle trough them by clicking on the system again, or you can select it on the System Info screen.

The map is divided to 8 light year cubes called sectors. Each sector has a coordinate on each axis; the origin (0,0,0) is Sol. The galaxy is not a flat disk, you can travel quite far on all three axes before you reach the edge of it.
'''Map view UI:'''
*'''Current system''': The system you are currently in, with sector coordinates and a brief info about it. The button next to it centers the view on it.
*'''Hyperspace target''': The system selected as hyperspace target. Shows the coordinates, distance, fuel and travel time needed to reach it, and a brief info about it. It can be locked with Space bar, that way it stays as target even if another system is selected.
*'''Selected system''': Shows the same info as Hyperspace target if that's not locked. If locked, it shows the same info for the selected system. Useful for system comparison or travel planning.
*'''Map view settings''':
**'''Draw vertical lines''': draws a vertical line from the stars in range to the plane of the map to show the height relative to that plane. Clarifies system positions a bit.
**'''Label out-of-range systems''': Toggles label display for systems that are out of range. The map only shows labels for systems in range by default, so it's a useful option if you look for a specific system for example.
**'''Label uninhabited systems''': Toggles label display for systems that are uninhabited (no settlements, spaceports).
*'''Hyperspace range''': the map draws a transparent sphere to show which systems are in jump range. Jump range depends on hyperdrive class, fuel on board and the total mass of the ship.
*'''View position''': On the lower left corner, distance and coordinate data are displayed regarding to the current view.

'''Map controls:'''
*'''Translation''': You can move around on the sector map using the '''arrow keys''' and '''Page Up''' and '''Page Down''' for vertical (forward/backward) movement. Movement is based on the view rotation.
*'''Rotation''': The view can be rotated with the '''W A S D''' keys, or with holding the '''Right Mouse button'''.
*'''Zoom''': You can zoom with the '''+''' and '''-''' keys, or with the '''Mouse wheel''', or using the two buttons on the top right.
*'''Faster controls''': Holding '''Shift''' speeds up movement and zoom. Use '''Right Shift''' for smaller speedup and '''Left Shift''' for quite fast movement.
*'''Selecting system''': Moving around on the map will automatically select the system closest to the center of the view. You can also select any system with the mouse.
**'''Selecting another star''' In a system with multiple stars (Binary or tertiary systems), you can cycle trough each star by clicking on the system again until you find the one you want to travel to.
**'''Lock selection''': You can lock your selection as the hyperspace target with the '''Space bar'''. This allows for selecting another system to plan a route, or could be useful for comparing systems.
**'''Center''': Pressing '''C''' centers the view on the system you are in. '''G''' centers on Selected system and '''H''' centers on the Hyperspace target.
*'''Reset view''': '''R''' resets view rotation, and zoom.
*'''Search''': You can type in the name of the system to the Search field on the lower right and it will select the system if it can be found. Note that it doesn't search the entire galaxy, only in a few tens of sectors range. You can also enter coordinates to move the map to any area.
*'''Tab''': Switches the left side info panel to faction filter.
'''Zooming out far'''

Zooming out far switches to an overview that only shows color-coded dots for systems based on faction, and brings up the faction filter to the right where you can hide any faction. Map controls are the same as before.

===Orbital map (F6)===
[[File:Manual_map_orbit_01.png|right|600px]]

You can switch to the Orbital map using F6. It shows the to-scale orbital map of the star system selected on the Sector map. It is useful for in-system navigation. It shows your current position and your course of movement, and the orbit of every body (star, planet, moon, space-station) in the system.

'''Controls''':
Controls of the orbital map are a bit different from the Sector map.
*'''Selection''': You can select any orbital body using your '''Left Mouse button'''.
*'''Targeting''': Any body can be targeted by holding '''Shift''' while selecting the body.
*'''Translation''':The view is always centered on the body selected. You can't move the view.
*'''Rotation''': You can rotate either by holding the '''Middle mouse button''', or by using Left Mouse Button on the rotation icon
*'''Zoom''': You can use the '''Mouse Wheel''' or the buttons on the top right for zooming. Shift accelerates zoom similar to the sector view.
*'''Time controls''': You can use these buttons to check the position of the bodies in the system (including your ship) in any given time. The button in the center resets it to the current time. This is useful for planning a flight. The set time is shown above the current time on the left.

The Orbital Map shows your position and course in the system, relative to your reference body, be it a stable orbit or an escape trajectory. You can use this to fine-tune your path while you are traveling to your destination for example. Or you can just check if you managed to achieve a stable orbit.

Time controls work on this too, you can check where you will be at any given time. Note that this course display might change when you switch reference bodies, for instance when you get close to a planet.

===System info (F7)===
[[File:Manual_map_info.gif|right|600px]]
This screen shows detailed info on the system. If the system has multiple stars, you can select which one you want to be the hyperspace destination, by clicking on it.

F7 switches between these views:

*'''Planetary info''': Shows a general system description. Hovering over any body with the mouse displays more detailed information, like orbital parameters, temperature, atmosphere composition. It also shows the star-ports on the surface of the body. Bodies that have settlement are circled for easier spotting. In systems with multiple stars, the one currently selected as hyper jump target is indicated with a square centered on it.

*'''Economics info''': Shows exports, imports of the system, and the illegal goods. Exported items are cheap, imported items are expensive, so this is a crucial screen for trading. Illegal goods can only be bought or sold at black market retailers found on the star-port BBS. Be careful though, some retailers are undercover cops who will fine you if you attempt to make business with them. Illegal items are based on factions. If you have selected a system other than the one you are currently in, it will compare imports/exports between them and mark commodities of special interest with Green (best, e.g. major export in system A is a major import in B), or white (Major/Minor export in A is a Minor/Major import in B). For Illegal goods only gray or red is used to show if it is legal in one of the systems but illegal in the other.

*'''Demographics''': Shows information on the system, like population, government type and faction.

===Galaxy map (F8)===
The galaxy map shows an overview of the whole galaxy, highlighting your current position. Brighter areas generally have more stars than darker areas.

==Info View (F3)==
You can access various information by pressing F3, or the Info View button on the dashboard.
===Ship Information===
[[File:Manual_infoview_01_ship.png|600px|right]]
[[File:Manual_infoview_02_commander.png|600px|right]]
[[File:Manual_infoview_03_cargo.png|600px|right]]

Shows information regarding your spaceship
*'''Hyperdrive & Hyperspace range'''
The class of hyperdrive installed on the ship. Higher class hyperdrives are heavier, but can jump to greater distances. Common hyperdrives consume Hydrogen, which can be bought on stations, or could be scooped from the atmosphere of gas giants, if the ship has a Fuel Scoop installed.

Military Drives are generally faster, but they use Military fuel, which is more expensive and harder to obtain. Military drives turn fuel into Radioactives that you need to get rid of.

Current Hyperspace range is displayed based on current ship mass and the amount of fuel in the cargo hold. You can see the theoretical maximum range shown in brackets. This changes as you fill your ship with cargo or fuel.

*'''Mass data'''
** Weight empty: Dry mass of the ship, without any cargo or propellant.
** Capacity used: Used and available cargo and equipment capacity of the ship.
** Fuel weight: Amount of propellant, and the maximum capacity of the tanks. Propellant is Hydrogen. Tanks are refilled upon docking or landing on a station, if the player has enough money ($1-6 usually). It's possible to buy extra Hydrogen in the Commodity Market for manual in-flight refill.
** All-up weight: Sum of hull, cargo and propellant mass.
*'''Weapons'''
Cannons installed on front and rear facing hard-point.
*'''Fuel & Delta-v'''
Propellant and delta-v reserves.
Delta-v shows, how much speed change can be done using the propellant in the tanks. Generally, more delta-v means faster in-system travel.

For a brachistochrone transfer (accelerating halfway, then decelerating) you can use up half of the delta-v. If you exceed that, then you will be unable to stop your ship. It's useful to save a good amount of delta-v (about 500-1000 km/s) for course corrections and landing.

Delta-v display doesn't take additional Hydrogen in the cargo hold into account, so refueling with Hydrogen can increase it. Ship mass can also change delta-v capability dramatically.

You can [[Hydrogen_scoop|scoop Hydrogen]] from the atmosphere of a gas giant, if you have Fuel Scoop installed.

You can mine water in the field, if you have a Mining Blaster and Cargo scoop. You need to find a planet that has water (a smaller moon or dwarf planet is easier to mine), shoot the surface and collect any water that's blasted out from it.
*'''Accelerations'''
Shows the acceleration the ship is capable of with it's current load. Displayed both in m/s^2 and Gee. A ship with higher acceleration will feel faster, especially around station. It affects travel times less then delta-v.

If Up acceleration is higher then the gravity of the planet, then the ship might not be able to take off or land, especially using the autopilot.

Acceleration increases while the ship uses its propellant, and can be further increased by jettisoning cargo. Selling cargo or equipment can help too.

*'''Crew'''
Minimum crew shows the needed head count to fly the ship (currently ignored). Crew cabin shows the crew capacity of the craft. Crew are useful in multiple ways, but you have to pay them weekly.

Crew can control the ship, engage the enemy or repair damages. Each crew member has strengths and weaknesses, their abilities improve by time.
*'''Equipment'''
Shows the list of installed equipment. These equipments enhance your ship's capabilities, and can even add functions to it.

===Personal Information===

Shows information about your character.
Currently you see your combat rating, reputation standing, and rank (however, the rank can not be changed in the game yet, and doesn't influence the game either).

Reputation affects mission availability, and can be increased by completing missions or donating to charities. Failed missions decrease your reputation.

You can also change your name, gender and face.

===Economy & Trade===

Shows the contents of the cargo hold in detail, and allows in-flight refueling.
You can find the list of cargo in your hold, and you can jettison any of them here while in flight. If you have Cargo Scoop installed, you can even retrieve the jettisoned cargo.

Refueling transfers 1t of Hydrogen, if available, to the propellant tanks.
Available and occupied passenger cabin space can be checked here too.

===Missions===
[[File:Manual_infoview_04_missions.gif|600px|right]]
Shows information about accepted missions. You can check the destination and deadline here, and you can see additional information about each mission, using the More info... button on the right.

You can find and take all kinds of missions on any star-port's BBS, but be sure to check if you and your ship is capable of completing it. Failing missions decrease your reputation, which makes it harder to find lucrative offers, so it will be harder to regain your reputation, so be cautious.

===Crew Roster===
[[File:Manual_infoview_06_crew.gif|600px|right]]
You can access information about your crew. It shows the salary which you need to pay them weekly. If you can't pay for a while, they will get off on the next port, with some of your reputation.

Some ships need multiple crew members on board even to fly it (this is ignored right now though), and they can perform several tasks, like piloting, engaging in combat or repairing the hull or failed equipment.

== Station view (F4)==
[[File:Manual_station_bbs.png|600px|right]]
[[File:Manual_station_market.png|600px|right]]
Access this screen with F4 or the comms icon on the dash board, while you are docked to a space-port, be it a surface base or an orbital station.
All screens show the cargo and passenger capacity of your ship, your money and legal status in the footer.

=== Lobby ===
It's a good idea to request launching clearance before taking off. The station dispatcher will stare at you until you get embarrassed and go about your business.

=== Bulletin Board ===

You will find missions of all sorts here on the BBS. Keep in mind that some might not be suited for your ship in terms of distance and deadline. Some missions are in-system, and will not require any hyperdrive, but will in turn pay less. You should check the system map even in this case, because planets might be in opposition on their courses and you end up traveling across the whole system which can take a while even with a high delta-v ship.

Some missions are riskier, so it's always a good idea to ask if there will be any danger, so you can prepare properly, or avoid the mission altogether until you are better rigged for combat for example.

Local hyperdrive maintenance companies offer their services here too. Old drives may start to misbehave, so if you don't want to strand yourself in the interstellar void, don't forget regular maintenance.

Charities can also turn up from time to time, asking for money for their cases. Donating to them could increase your reputation.

When you start a new game, you will not have any reputation, which must be earned by taking on missions (or donating to charities). You can see your current reputation standing in your personal Info view. Reputation affects what kind of missions you can take on. Completing a mission will increase your reputation, and opens up more job opportunities, and failure decreases it, narrowing the available mission after a while.

Some stations have private black market goods dealers who trade in illegal goods, although some might be undercover police.

You can also hire new crew members if you are in need. Make sure to have good candidates on the BBS before buying a new ship. You can make them sit a test to show their abilities (though those doesn't affect the game right now), and you can negotiate their pay too.

If no mission suits you, then something new might pop up over time. Missions that require better reputation are grayed out, and the advertiser won't talk with you much.

=== Commodity Market ===

You can buy and sell commodities here. Keep in mind, that a heavy ship will have shorter hyperspace range. You can also buy Hydrogen or Military fuel for your hyperdrive here.
You just need to click on the name of the commodity on the left side to buy 1t of it. The contents of your cargo hold are on the right side, clicking on any item will sell 1t of it. Buy and sell prices are the same right now.

Prices depend on the type of the system. Agricultural systems will pay a lot for farm machinery for example, and you can buy cheap foodstuff. An industrial system on the other hand sells cheap machinery, and pays good money for food. You need to scout out lucrative routes for yourself if you want to turn profit.

Illegal goods can't be found on the market, you need to look for a black market retailer on the BBS. Note that one item can be completely legal in one system, but illegal in another.

=== Shipyard ===
[[File:Manual_station_shipmarket.png|600px|right]]
You can buy ships here, trading in your current ship with all of its additional equipment or cargo.
You can check out the capabilities and stats of the ships offered for purchase, much like the information you have on the Info view screen. The ''After Trade-in'' is the final price you need to pay, and if it's negative, it means your current ship worths more then the one you are looking at. Trade-in value is about the half of the list value of any ship.

Ships are traded continuously, so you just need to wait a few hours if there's nothing interesting there, and new vessels will turn up.

=== Equipment Market ===
Buy/sell equipment for your ship. Equipment market works similar to the commodities market. Left side shows what's available on the station, right side shows, what's installed on your ship.
Each equipment has a certain mass, so they occupy space on the ship much like cargo. heavier ships are harder to maneuver, and their delta-v and hyperspace range also decreases. You can't remove any equipment while you are flying, except for using missiles.
Equipments add extra capabilities to your ship, like radar and targeting information, autopilot, cargo and fuel scooping ability. You can buy weapons, shields and some upgrades to these too.

=== Ship Repairs ===
Maintaining your ship is important, unless you want to be stranded in an uninhabited system or interstellar space due yo your hyperdrive failing.
You can repair your hull here too, if needed.

=== Police ===
If you have any fines you need to pay them or else risk getting shot down by some restless police officer.
You can get in trouble for trading with illegal goods, or even if you accidentally fire your weapon near any settlement. In the later case it's better to run, then pay the fine later.

User:Sturnclaw

2021-10-08T13:25:32Z

Sturnclaw:

Hello! My name is Sturnclaw. Your code offends me. Prepare to die.

In more serious words, I'm known as Sturnclaw around here. In demeanor, I'm pretty much your typical overconfident software engineer who thinks he can do anything given enough time and sauerkraut – I'll leave the verification of that claim up to the reader.

A cursory search will reveal that I'm the owner and head of Web eWorks, LTD, and when I'm not busy with that or one of a number of side projects, I work on Pioneer to brush up my C++ skills.

You can find me on Github as [https://github.com/web-eworks Web eWorks], or on IRC as sturnclaw.

== The List ==

Upon the recommendation of several members of the team, I have begun to curate The List, stored right here on this page.

What is "The List", you ask? The List is basically a copy of Pioneer's roadmap, kept fairly current to the latest IRC <s>fantasizing</s> plans, and annotated with my thoughts and recommendations for implementation. It is estimated that completing all of the items on The List will take between 5 and 15 person-years of development work, so if you want to implement something here, go right ahead.

Without further ado, I present The List:

=== Core Tech: ===

==== Entity Component System (ECS) Model ====
Convert the Pioneer codebase to use a composition-based model instead of an inheritance-based model.
* The rationale behind this decision is that an inheritance-based architecture for gameplay objects is generally unsustainable without some form of composition, especially so when mods are involved - what if your mod wants to add a different implementation of a hyperdrive?
* This will be a multi-step process:
** Implement some minor features using the ECS paradigm to get started and evaluate requirements. '''Working'''
** Drive the new ECS-based features from existing code as a temporary measure. '''Working'''
** Convert a major feature (Ship, BodyOnPlanet, etc) to use the ECS.
** Continue converting major features until all applicable areas of the code are converted.

==== Input System ====
Before I started working on Pioneer, the input system was particularly archaic; inputs were defined with macros in a single file that got <nowiki>#include</nowiki>d into about 4 different files and compiled into the binary - needless to say, if you wanted a new input axis or action, you had to recompile the entire game.

The input system is currently being refactored into a modular, moddable system which supports sharing axes between systems and modules and defining entirely new axes and actions in mods.

This change is about half done - the technical underpinnings of the system are mostly finished, and all that's left is to expose it to Lua.

Planned Features:
* Modular, Lua-exposed input system '''WORKING'''
* Key-chord inputs, allowing arbitrary modifier keys / buttons. A software "pinkie switch" if you will. '''DONE'''
* Frame-based input grouping system, allowing multiple conflicting "modes" to be enabled or disabled en-bloc. '''DONE'''
* Touchscreen input for camera and flight controls. (Investigate: virtual joysticks or whole-screen mouse emulation?)

==== Model System ====
The model system needs further work and refactoring. It currently bloats savefiles excessively, has a very limited API that ignores file paths, is a pain to build files for release builds, and cannot be multi-threaded.

Planned Improvements:
* Don't store a list of transform visitors in savefiles; animations should be responsible for node positioning. Possibly use a dirty flag to only store nodes that have been explicitly positioned by code? '''DONE'''
* Refactor all code and data that touches models to use full paths instead of just the basename component.
* Refactor model loading to make it asynchronous; run the load step on a separate thread, and add an end-of-frame task on the main thread to upload model data to GPU
* Allow ModelBody to cache collision objects. This will likely come hand in hand with not creating separate Model instances.

==== Lua Engine ====
Coming on the heels of the input changes are improvements to Pioneer's Lua engine. At current, Pioneer is using its own feature-incomplete version of <nowiki>require()</nowiki> (used as <nowiki>import()</nowiki>), which supports a very limited method of calling other code files. Additionally, the C++ side of the Lua interface has issues with handling Lua errors - if C++ calls a lua function that errors, the whole engine terminates with an error.

There are several goals to accomplish here, but the major two are:
* Update <nowiki>import()</nowiki> to support Lua 5.2+ style "module.submodule" syntax and implicit "init.lua" support. '''DONE'''
* Deprecate <nowiki>import()</nowiki> in favor of <nowiki>require()</nowiki> to support languages that target Lua. '''DONE'''
* Make throwing a Lua error safe with regards to C++ code, and support arbitrarily disabling a Lua module if it is throwing an error. '''WORKING'''
** E.g. if a specific part of the UI throws an error, silently catch it and log it. If it keeps throwing errors, disable the module and inform the user. This is going to require some significant work, but it will make the modding and content-creation ecosystem much more user-friendly.

Tangentially to the ECS changes, we need a better method of binding C++ code and data to Lua. Currently the hand-written method is serviceable, but it is akin to "implementing the same thing twice", doubling the workload for anyone wanting to add something new.
* Add an automatic solution for binding C++ code to Lua, capable of auto-generating bindings for properties, methods, and POD-structs and full LuaObject classes. '''DONE''' (see LuaMetaType.h)

=== Gameplay: ===

There are a ''huge'' number of new features and wild gameplay ideas that I and others would really like to see added to the game, but this is a more reasonable list of features that can actually be implemented with a few months of work.

* Refactor the camera / view system to better support inputs, allow arbitrary spectator / debug cameras for editor mode, enable first-person and turret cameras. '''WORKING'''
** Add a "camera offset" axis for internal / cockpit view that can be hooked up to headtracking. '''DONE'''
** Make the existing camera system use the new InputFrames for input. '''DONE'''
** Decouple camera systems from the concept of a ship to make them suitable for debug/flying cameras. '''WORKING'''
** Add cameras for turrets.
* Completely rewrite the weapons systems to support arbitrary guns and turrets, as well as a better loadout system. '''WORKING'''
** Arbitrary fixed gun mounts. '''WORKING'''
** Turret hardpoints
** Missile racks / hardpoints
* Rework drag and atmospheric heating to be somewhat accurate. '''WORKING'''
* Implement atmospheric lift so aerodynamic ships can fly. '''DONE'''
* Add airframe damage due to excessive G-force and/or dynamic pressure when flying in atmosphere.
** Possibly damage specific components (landing gear, control surfaces, etc) reducing their effectiveness and/or destroying them.

Higher-level gameplay refactor features include:

* Support procedurally-generated 'planetary outpost' buildings that have to be discovered / scanned.
** Load outpost configurations from a scene file of some sort?
* Add power, heat, and EM system simulations to ships.
** Power is generated by reactor and/or engines, used to operate most ship systems.
** Heat generated by engines, shields, and weapons; vented through radiators and atmosphere.
** EM is generated by all systems and used to determine ship sensor profile.
* Dynamic ship sensor contact system
** Ships no longer always show up on the map, they have to be "visible" to the player
** Add scanner mode to discover outposts, ships, etc
** Dynamic signal strength approximation allowing reasonable stealth gameplay
** Planetary occlusion of signals

=== Rendering: ===

==== PBR Rendering Engine ====

Convert Pioneer to a Clustered Forward or Clustered Deferred rendering model. This change needs to implement support for numerous lights, mesh decals ala Star Citizen, accurate terrain rendering with high-res texturing support via material layering and distance-dependent detail texturing, a full postprocessing chain including bloom, chromatic aberration, motion blur, and an AO implementation (perhaps an HBAO or SSAO variant), support for atmospheric shading, etc.

Reference:
* [https://turanszkij.wordpress.com/2017/10/12/forward-decal-rendering/ Forward+ Decal Rendering]
* [https://google.github.io/filament/Filament.md.html Filament Renderer], an open-source mobile-capable Clustered Forward PBR renderer, with accompanying whitepaper.
* [http://www.cse.chalmers.se/~uffe/clustered_shading_preprint.pdf A paper on clustered rendering]
* [http://www.thetenthplanet.de/archives/4519 Atmospheric Scattering] with link to implementation.

'''Clouds'''

Possibly using a low-resolution voxelized implementation, atmospheric clouds are a planned feature. They'd need to support transparency, layer over each other without killing performance, and look at least moderately good. Flat clouds are also required when looking at a planet from orbit, which could be static textures or generated from a basic weather simulation for believable construction.

''' Mesh Decals '''

TODO: link in nozmajner's ship decal work, pontificate about supporting that engine-side.

=== Content: ===

* Finish modelling and texturing the Sador Heavy Fighter, including setting it up to use turrets and a new gun / missile system.

User:Sturnclaw

2021-10-08T13:24:17Z

Sturnclaw:

Hello! My name is Sturnclaw. Your code offends me. Prepare to die.

In more serious news, I'm known as Sturnclaw around here. In demeanor, I'm pretty much your typical overconfident software engineer who thinks he can do anything given enough time and sauerkraut – I'll leave the verification of that claim up to the reader.

A cursory search will reveal that I'm the owner and head of Web eWorks, LTD, and when I'm not busy with that or one of a number of side projects, I work on Pioneer to brush up my C++ skills.

You can find me on Github as [https://github.com/web-eworks Web eWorks], or on IRC as sturnclaw.

== The List ==

Upon the recommendation of several members of the team, I have begun to curate The List, stored right here on this page.

What is "The List", you ask? The List is basically a copy of Pioneer's roadmap, kept fairly current to the latest IRC <s>fantasizing</s> plans, and annotated with my thoughts and recommendations for implementation. It is estimated that completing all of the items on The List will take between 5 and 15 person-years of development work, so if you want to implement something here, go right ahead.

Without further ado, I present The List:

=== Core Tech: ===

==== Entity Component System (ECS) Model ====
Convert the Pioneer codebase to use a composition-based model instead of an inheritance-based model.
* The rationale behind this decision is that an inheritance-based architecture for gameplay objects is generally unsustainable without some form of composition, especially so when mods are involved - what if your mod wants to add a different implementation of a hyperdrive?
* This will be a multi-step process:
** Implement some minor features using the ECS paradigm to get started and evaluate requirements. '''Working'''
** Drive the new ECS-based features from existing code as a temporary measure. '''Working'''
** Convert a major feature (Ship, BodyOnPlanet, etc) to use the ECS.
** Continue converting major features until all applicable areas of the code are converted.

==== Input System ====
Before I started working on Pioneer, the input system was particularly archaic; inputs were defined with macros in a single file that got <nowiki>#include</nowiki>d into about 4 different files and compiled into the binary - needless to say, if you wanted a new input axis or action, you had to recompile the entire game.

The input system is currently being refactored into a modular, moddable system which supports sharing axes between systems and modules and defining entirely new axes and actions in mods.

This change is about half done - the technical underpinnings of the system are mostly finished, and all that's left is to expose it to Lua.

Planned Features:
* Modular, Lua-exposed input system '''WORKING'''
* Key-chord inputs, allowing arbitrary modifier keys / buttons. A software "pinkie switch" if you will. '''DONE'''
* Frame-based input grouping system, allowing multiple conflicting "modes" to be enabled or disabled en-bloc. '''DONE'''
* Touchscreen input for camera and flight controls. (Investigate: virtual joysticks or whole-screen mouse emulation?)

==== Model System ====
The model system needs further work and refactoring. It currently bloats savefiles excessively, has a very limited API that ignores file paths, is a pain to build files for release builds, and cannot be multi-threaded.

Planned Improvements:
* Don't store a list of transform visitors in savefiles; animations should be responsible for node positioning. Possibly use a dirty flag to only store nodes that have been explicitly positioned by code? '''DONE'''
* Refactor all code and data that touches models to use full paths instead of just the basename component.
* Refactor model loading to make it asynchronous; run the load step on a separate thread, and add an end-of-frame task on the main thread to upload model data to GPU
* Allow ModelBody to cache collision objects. This will likely come hand in hand with not creating separate Model instances.

==== Lua Engine ====
Coming on the heels of the input changes are improvements to Pioneer's Lua engine. At current, Pioneer is using its own feature-incomplete version of <nowiki>require()</nowiki> (used as <nowiki>import()</nowiki>), which supports a very limited method of calling other code files. Additionally, the C++ side of the Lua interface has issues with handling Lua errors - if C++ calls a lua function that errors, the whole engine terminates with an error.

There are several goals to accomplish here, but the major two are:
* Update <nowiki>import()</nowiki> to support Lua 5.2+ style "module.submodule" syntax and implicit "init.lua" support. '''DONE'''
* Deprecate <nowiki>import()</nowiki> in favor of <nowiki>require()</nowiki> to support languages that target Lua. '''DONE'''
* Make throwing a Lua error safe with regards to C++ code, and support arbitrarily disabling a Lua module if it is throwing an error. '''WORKING'''
** E.g. if a specific part of the UI throws an error, silently catch it and log it. If it keeps throwing errors, disable the module and inform the user. This is going to require some significant work, but it will make the modding and content-creation ecosystem much more user-friendly.

Tangentially to the ECS changes, we need a better method of binding C++ code and data to Lua. Currently the hand-written method is serviceable, but it is akin to "implementing the same thing twice", doubling the workload for anyone wanting to add something new.
* Add an automatic solution for binding C++ code to Lua, capable of auto-generating bindings for properties, methods, and POD-structs and full LuaObject classes. '''DONE''' (see LuaMetaType.h)

=== Gameplay: ===

There are a ''huge'' number of new features and wild gameplay ideas that I and others would really like to see added to the game, but this is a more reasonable list of features that can actually be implemented with a few months of work.

* Refactor the camera / view system to better support inputs, allow arbitrary spectator / debug cameras for editor mode, enable first-person and turret cameras. '''WORKING'''
** Add a "camera offset" axis for internal / cockpit view that can be hooked up to headtracking. '''DONE'''
** Make the existing camera system use the new InputFrames for input. '''DONE'''
** Decouple camera systems from the concept of a ship to make them suitable for debug/flying cameras. '''WORKING'''
** Add cameras for turrets.
* Completely rewrite the weapons systems to support arbitrary guns and turrets, as well as a better loadout system. '''WORKING'''
** Arbitrary fixed gun mounts. '''WORKING'''
** Turret hardpoints
** Missile racks / hardpoints
* Rework drag and atmospheric heating to be somewhat accurate. '''WORKING'''
* Implement atmospheric lift so aerodynamic ships can fly. '''DONE'''
* Add airframe damage due to excessive G-force and/or dynamic pressure when flying in atmosphere.
** Possibly damage specific components (landing gear, control surfaces, etc) reducing their effectiveness and/or destroying them.

Higher-level gameplay refactor features include:

* Support procedurally-generated 'planetary outpost' buildings that have to be discovered / scanned.
** Load outpost configurations from a scene file of some sort?
* Add power, heat, and EM system simulations to ships.
** Power is generated by reactor and/or engines, used to operate most ship systems.
** Heat generated by engines, shields, and weapons; vented through radiators and atmosphere.
** EM is generated by all systems and used to determine ship sensor profile.
* Dynamic ship sensor contact system
** Ships no longer always show up on the map, they have to be "visible" to the player
** Add scanner mode to discover outposts, ships, etc
** Dynamic signal strength approximation allowing reasonable stealth gameplay
** Planetary occlusion of signals

=== Rendering: ===

==== PBR Rendering Engine ====

Convert Pioneer to a Clustered Forward or Clustered Deferred rendering model. This change needs to implement support for numerous lights, mesh decals ala Star Citizen, accurate terrain rendering with high-res texturing support via material layering and distance-dependent detail texturing, a full postprocessing chain including bloom, chromatic aberration, motion blur, and an AO implementation (perhaps an HBAO or SSAO variant), support for atmospheric shading, etc.

Reference:
* [https://turanszkij.wordpress.com/2017/10/12/forward-decal-rendering/ Forward+ Decal Rendering]
* [https://google.github.io/filament/Filament.md.html Filament Renderer], an open-source mobile-capable Clustered Forward PBR renderer, with accompanying whitepaper.
* [http://www.cse.chalmers.se/~uffe/clustered_shading_preprint.pdf A paper on clustered rendering]
* [http://www.thetenthplanet.de/archives/4519 Atmospheric Scattering] with link to implementation.

'''Clouds'''

Possibly using a low-resolution voxelized implementation, atmospheric clouds are a planned feature. They'd need to support transparency, layer over each other without killing performance, and look at least moderately good. Flat clouds are also required when looking at a planet from orbit, which could be static textures or generated from a basic weather simulation for believable construction.

''' Mesh Decals '''

TODO: link in nozmajner's ship decal work, pontificate about supporting that engine-side.

=== Content: ===

* Finish modelling and texturing the Sador Heavy Fighter, including setting it up to use turrets and a new gun / missile system.

Strings and translation

2021-10-08T12:46:49Z

Sturnclaw: Clarity edits, reference lua-5.2 documentation.

==Internationalization==
Recommended reading: [https://pioneerwiki.com/wiki/Translations Pioneer translators wikipage]

It is important that scripters are familiar with the translation system. In the previous example '''hello_world.lua''' used strings directly like <code>print("Hello, World!")</code>. In order for Pioneer to be translated we instead use tokens and calls on the <code>'Lang'</code> module to substitute it for the string in the chosen language. The translated strings are stored together with their 'key' in json format, one language per file that are kept in the [https://github.com/pioneerspacesim/pioneer/tree/master/data/lang data/lang/] directory. If the script file in which they are used is from the '''data/modules''' directory they have names starting with '''module-''' and ending with the name of the module written in one word, in small caps, and with the '.lua' ending omitted. The final translation from English to other languages is done on Pioneer's project page at [https://www.transifex.com/pioneer/pioneer/ Transifex], a dedicated online translation tool. The translations are committed to the pioneer/master branch on GitHub by a bot and are not to be edited manually apart from the '''en.json''' files.

==Translating strings==

Below is a minimal example with one string added into the translation system. It takes two files, one in '''data/modules''' and one in '''data/lang/module-hello'''. The print statement isn't wrapped in a function so it will be executed when the '''hello.lua''' is being parsed on startup. You will have to scroll through the command-line history to find it interleaved with the other output.

'''data/modules/hello.lua'''.
local Lang = require 'Lang'
local l = Lang.GetResource("module-hello")

print(l.HELLO)

And a corresponding file containing the translated string, and a description field shown to the translator, giving the context.

'''data/lang/module-hello/en.json'''
{
"HELLO": {
"description": "A classic message.",
"message": "Hello World!"
}
}

In short, any script containing strings that needs translation needs to load the <code>'Lang'</code> module:
local Lang = require 'Lang'
Then load the translation resource they want to use in their module, often just named <code>'l'</code> as in:
local l = Lang.GetResource("module-hello")

Note: Selecting any other language than a non-English, e.g. Esperanto, will trigger the game to crash, as it will try to replace the english string with a non-existing Esperanto file. This is only an issue when you're working on your code locally, once the script is merged into the master branch, Transifex will duplicate it to all supported languages, and copy it back into the main source repo.

==Working with strings==

Recommended chapters from [https://www.lua.org/pil/contents.html Programming in Lua (first edition) ] 
[https://www.lua.org/pil/2.4.html 2.4 – Strings] 
[https://www.lua.org/pil/3.4.html 3.4 – Concatenation] 
[https://www.lua.org/pil/20.html 20 – The String Library] 
And from the [https://www.lua.org/manual/5.2/ Lua 5.2 Reference Manual] 
[https://www.lua.org/manual/5.2/manual.html#6.4 6.4 – String Manipulation] 

===Concatenation===

Instead of serving ready made sentences we can stitch them together with the Lua string concatenation operator <code>..</code>. The following codelines result in the same output.
print("Hello Clarice!")
print("Hello" .. " " .. "Clarice!")

This could be created by the more generic:

local Comms = require 'Comms'
local Event = require 'Event'
local Game = require 'Game'
local NameGen = require 'NameGen'

local GREETING = 'Hello'
local FBIAGENT = NameGen.Surname()

local onShipDocked = function (ship)
if ship == Game.player then
Comms.Message(GREETING .. ' ' .. FBIAGENT .. '!')
end
end

Event.Register("onShipDocked", onShipDocked)

The <code>..</code> operator is used all over the codebase. Try a search for its occurrence. On Linux I would do <code>grep -R " \.\. " data/modules/ data/libs/ data/pigui/</code> and that will render a lot of output.

===Lua Standard Library - String manipulation===

I would start to search the '''data/''' register for ''''string.'''' to get a feeling for how it's used. Again on Linux i would use the 'grep' command. <code>grep -R "string\." data/</code>. You will see that the two most frequently used functions is <code>string.format(</code>, which is a part of the lua standard library, and <code>string.interp()</code>, which is a Pioneer global function residing in '''data/libs/autoload.lua''' and is described in the next paragraph.

Some examples from the Lua standard library:
Comms.Message(string.lower('wHaT cAsE sHoUlLd I usE?'))

Maybe not the most easy function to fit into Pioneer. But it's there:
Comms.Message('Today is opposite day!')
Comms.Message(string.reverse('No, today is not opposite day!')

A more complex example from '''[https://github.com/pioneerspacesim/pioneer/blob/452e9468bc32b844b379307f982c5869733bd85b/data/pigui/modules/hyperjump-planner.lua#L140 data/pigui/modules/hyperjump-planner.lua]''' 
Here <code>string.format("%.2f", distance)</code> is used to set the number of decimals in the jump to two. The rest is string variables that are not translated (names) and string concatenation. '''lc''' is used as the short name for the '''core''' translation resource. 
textLine = jumpIndex ..": ".. jump_sys.name .. " (" .. string.format("%.2f", distance) .. lc.UNIT_LY .. " - " .. fuel .. lc.UNIT_TONNES..")"

Here is what the final formatted text looks like (right side, two selected jump routes): 
[[File:hyperjumpplanner.png]]

==String variables==

When you want a string to present variable data such as numbers and names you use the <code>interp()</code> function. <code>interp()</code> accepts a table '{}' and the corresponding keys are then embedded in the translated strings enclosed by curly brackets '{}'.

Using ''''module-stationrefuelling'''' we can do:
print(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = 'JFK', fee = 50}))

Example from the actual StationRefuelling module:

'''data/modules/StationRefuelling/'''
Comms.Message(l.WELCOME_TO_STATION_FEE_DEDUCTED:interp({station = station.label,fee = Format.Money(fee)}))

'''data/lang/module-stationrefuelling/en.json'''
"WELCOME_ABOARD_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, docking in orbit",
"message": "Welcome aboard {station}. Your docking fee of {fee} has been deducted."
},

'''data/lang/module-stationrefuelling/es.json'''
"WELCOME_ABOARD_STATION_FEE_DEDUCTED": {
"description": "Station welcome message, docking in orbit",
"message": "Bienvenido a bordo de {station}. Le ha sido deducida su cuota de atraque de {fee}."
},

FAQ

2021-01-12T18:35:34Z

Sturnclaw: Update joystick section.

= Frequently Asked Questions =

== About the Game ==

=== What is Pioneer? ===

Pioneer is a freeform single player space adventure in the spirit of [https://en.wikipedia.org/wiki/Frontier:_Elite_II Frontier: Elite II].

=== Is this a game or a simulation? ===

Frontier was a game, but with a newtonian flight model and a slightly more scientific flavour to the universe than usually in space games. Pioneer follows this same path.

=== Can I play online? ===

There will be no multiplayer. This does not rule out the possibility of minor network features, but multiplayer as it is commonly known is not compatible with the core mechanics of Pioneer. See for instance [[Network_features|Network features]], and [[ServerAgent|ServerAgent]] for more, or our dev-forum [http://pioneerspacesim.net/forum/viewtopic.php?f=3&t=216 here]

=== Can I colonize planets, build space stations or conquer the universe? ===

No, these are out of the game scope. While the game universe might not stay static for the duration of a game, the player can not generally influence major events.

=== Can I walk around space stations and planets? ===

No, you cannot exit your ship. The ship is always your avatar. The development team does have [https://pioneerspacesim.net/forum/viewtopic.php?f=3&t=454 aspirations] to push in this direction, for future versions.

=== Is the universe pre-defined or randomly generated? ===

There are millions of stars in the galaxy. A few hundred on them are based on real-world astronomic catalogues. some of the planets (obvious ones being in the Sol system) are pre-defined, but most things are procedurally generated. This means that a planet does not exist until you actually visit it, but it will be generated the same way for every player.

=== Can I hire crew for my ship? ===

Yes. You can hire crew. But they don't do very much at the moment.

=== Are savegames compatible between releases? ===

The development of the game can happen in sudden bursts, some of which change the game universe, or save/load routine, such that old saves are blocked from loading, lest the game might crash. The player can start a new game, and "give" themselves back money, kills, reputation, ship, as it was in the old save, by using the [[Lua_Console|lua console]].

=== Are savegames compatible between Mods? ===

Again as with savegames between different versions of pioneer, compatibility between mods can not be guaranteed. It all depends on what mods you have installed.

=== Where is star system X from Frontier? Can I buy ship Y? ===

Although Pioneer started out as a clone of Frontier, it no longer is, thus references to the Frontier universe have been removed, and we aim at making Pioneer far better than Frontier. Thus, you will have to figure out new trade routes! But don't worry, Newtonian physics will remain, as well as single player.

== Gameplay ==

=== How do I take screenshots? ===

Ctrl+Printscreen saves .png files in the same directory where the game .ini and savegames are. You can cycle through full HUD/HUD without labels and cursor/No HUD and cockpit using TAB as described in [http://pioneerwiki.com/wiki/Keyboard_and_mouse_controls#In_flight [1]].

=== How do I find star X in the star map ===

First it is important to note that just like in real life, names are not unique. The star map allows the player to search for either name or coordinates of a system. The search is done in the local region of the currently selected system.

Thus a standard way of finding a system is to type in the name in the search field in the star map (generally refereed to as "sector view"). If you know the system is within a few ly from your position, then have your current location selected when you do the search, since it only does a "local" search in space. If the search fails, go to the sector where the star is supposed to be, either by typing the coordinates into the search field, or by using arrows, mark a nearby star in that system, and do another search. You can scroll the star map super fast by holding in the Shift key.

=== I have a Taxi mission to system X, but which starport? ===

For Taxi missions any starport will do, as long as you dock before the deadline.

=== Starsystem names are not unique ===

This is not a bug, space is big, and just here on Earth it is quite common with cities and villages sharing the same name, sometimes quite close.

=== I picked up a mission to a starport in a system, but when I search for the system, it seems that it doesn't have the destination starport, or even uninhabited. ===

As mentioned above, there could be multiple systems with the same name. Each mission states the coordinates (Sirius (1,0,-1) for example) of the destination system, and you can enter them into the search field on the sector map, to find the correct system.

=== I end up "a big number" AU away from the star when I hyper jump to a system ===

This happens in binary star systems. You can select the star you want to jump to from the [[Manual#System_info|System View]].

== Technical FAQ ==

=== How/where do I report my bug/crash ===

Bug reporting is the most important part where you as a player can help the community. When you encounter something that seems strange or odd in the game, please report it, preferably to our [https://github.com/pioneerspacesim/pioneer/issues issue tracker], but you can also stop by the [http://webchat.freenode.net/?channels=#pioneer IRC channel].

When having problems with graphics, or pioneer not starting/crashing, please attach the files '''output.txt''' and '''opengl.txt''' from the pioneer [http://pioneerwiki.com/wiki/FAQ#Where_is_the_configuration_file.2C_saved_games.2C_screenshots.3F config folder] in your home folder / My Documents folder. If you didn't get the '''output.txt''' file, then make sure '''RedirectStdio=1''' in '''config.ini'''.

It is important to include as much of the following information as possible in each issue report, much of this is available to use from the '''output.txt''' and '''opengl.txt''' but if you cannot attach them then please tell us:

*The version of pioneer you are trying to run (''build date or ingame version number'')
*What operating system you are running, Windows XP/Vista/7/8/10, Linux (''what distribution''), OSX.
*Your computers system specifications - CPU / RAM / Graphics card.
*Whether you have downloaded it from our site, or if you are building it from the source code.

=== Where is the configuration file, saved games, screenshots? ===

*Windows: My Documents\Pioneer
*OS X: /Users/your_username/Library/Application Support/Pioneer
*Linux: /home/your_username/.pioneer

=== Where is the Mac version? ===

Pioneer's development team is mainly on Linux and Windows, and does currently not have the ability to build and maintain a Mac version. To build a Mac release we actually need access to a Mac machine, which, unfortunately, none of the developers currently have. If you have a Mac which can compile and upload pioneer for us on a regular basis, then please contact us (IRC).

 

=== My OpenGL Version is below 3.1, "Pioneer cannot run on your graphics card" ===

UPDATE: Pioneer dropped 2.1 support in September, 2018. You need to checkout and compile a version prior to this, and do:

Open your pioneer configuration file, and set: "RendererName=Opengl 2.1". This should allow pioneer to run, provided your hardware supports OpenGL 2.1, which it should if you were able to run Pioneer up until 2014-11-18 when support was dropped. Note, support for multiple renderers was added 2017-03-03, i.e. both OpenGL 2.1 and 3.1; however, you need to edit your configuration file to select the proper one, as no auto-detection is done. Actually, if your hardware isn't extraordinarily old, OpenGL 3.1 should be supported if you update your drivers.

You can also find older versions (pre 20141119 on [http://www.moddb.com/games/pioneer/downloads moddb].

=== Where do I find older versions of Pioneer ===

You can find older versions starting from December 2014 (2014-12-05) on our [http://sourceforge.net/projects/pioneerspacesim/files sourceforge] page. 2014-11-18 was the last version supporting OpenGL 2, between 2014-11-19 to 2014-12-07 Pioneer required OpenGL 3.2. From 2014-12-08 only OpenGL 3.1 is required. Over at [http://www.moddb.com/games/pioneer/downloads moddb] they have windows version going further back in time.

=== I'm getting graphical issues ===

Such as wrong textures, ships missing from the view, text display glitches. '''Updating the display drivers usually solve these problems.'''

These usually occur on older graphics adapters, or because of outdated GPU drivers. Not too old NVidia and ATI cards are usually enough to play the game, but integrated GPUs are usually not enough.

=== I'm getting graphical issues, such as snow-like sky and transparent terrain ===

This is probably caused by the eclipse shader which isn't supported by some open source graphic drivers. You could install the proprietary drivers, if available, or disable the eclipse effect by adding DisableEclipse=1 to your pioneer configuration file (config.ini).

=== I see blank untextured Gas Giants and I'm using an ATI graphic card under GNU/Linux with open source drivers (Mesa R600) ===

With chipsets using the R600 gallium drivers the shader fails to compile. There is a workaround that uses less noise octaves. This produces less detailed texture maps for the gas/ice giants but they still look good and at least the program runs.

Try setting <code>AMD_MESA_HACKS=1</code> in ~/.pioneer/config.ini or disable GPU jobs entirely by setting <code>EnableGpujobs=0</code>

=== I'm getting text rendering artefacts ===

Some system monitoring HUD utilities, like MSI Afterburner, and Steam overlay can cause distorted text rendering. Try switching them off. 

=== The game freezes at the intro screen ===

If you cannot start the game at all, edit the configuration file and change value DisableShaders to 1.

=== The game crashes on start with an error message about imgui_draw.cpp ===

Check if any parent folder of Pioneer has any accented letters (e.g éáűúóü etc.). If so, copy the game to somewhere, where there's none of these in the folder tree.

=== The game crashes after the loading screen. I'm using ATI free drivers on GNU/Linux. ===

If you are getting a GL_INVALID_ENUM in console, could be because some ships uses textures in a format that, because of patents, is not included in the main mesa package. Search for libtxc-dxtn or libtxc_dxtn in your distribution and install it.

=== The game hangs when I turn on the ''Enable Cockpit (EXPERIMENTAL)'' option ===

It's because it's an experimental feature right now, infrastructure mostly. You need a cockpit model for to be able to use it.

You can find one heavily WIP one posted on the Community Forums. Note that it's a highly experimental feature right no, so please treat it accordingly.

=== My joystick is "drifting" ===

It's recommended that you calibrate your joystick using the OS facilities (Joystick Settings on Windows, jstest-gtk on linux) as this fixes 99% of all issues with incorrectly configured joysticks. However, if you want to adjust specific parameters for each joystick axis, support for customizable deadzone and sensitivity is available through the configuration file. Open config.ini and adjust the deadzone (DZ) and sensitivity exponent curve (CV) values of the corresponding axis to your liking.

; example joystick configuration
[Joystick.03000000a30600006404000000010000]
Axis0=DZ0.0 CV1.0
Axis1=DZ0.0 CV1.0
Axis2=DZ0.0 CV1.0
Axis3=DZ0.0 CV1.0
Name=Saitek Cyborg USB Stick

=== I'm getting poor performance ===

The heaviest part of the game is planetary terrain generation. Turn down the "Detail distance" and "Fractal detail" settings, they have the most impact for performance. Reducing screen resolution is also recommended, this can be done in the [[Settings_Menu|Settings Menu]], or manually to a custom values by editing your personal configuration file, on Linux: <code>~/.pioneer/config.ini</code>. On Windows: <code>Documents/pioneer/config.ini</code> Look for <code>ScrHeight</code> and <code>ScrWidth</code> entries. Also consider reducing number of buildings in cities.

=== I've enabled anti-aliasing in the config file, but it does not work ===

Make sure the AA settings are not overridden by your graphics card settings, on NVidia AA should be set to "application controlled" mode.

 

=== Full screen mode is incorrectly scaled ===

If you are on Windows, try:
<pre>Sounds like windows 7 desktop-scaling issues.
Try adding some compatability modes to the Pioneer.exe.
Right click it and Choose properties -> Compatability -> Tick
Disable desktop scaling, and Disable desktop composition.
</pre>

== Development ==

=== What's the history of Pioneer ===

The project started in 2008 by Tom Morton, and was [https://web.archive.org/web/20150326115725/http://spacesimcentral.com/ssc/topic/742-pioneer-new-gpl-frontier-elite-2-style-game/ announced in 2010] on the Space Sim Central forum (for space games), and on [https://forums.frontier.co.uk/threads/the-pioneer-thread.1596/ frontier forum]. For more history, see [http://www.rockpapershotgun.com/2011/12/06/back-to-frontier-pioneer/ Rock Paper Shotgun article], and [[Media_Coverage]]

=== How much development is being made? ===

Development is sporadic, but no month goes by without some change to the source, fixing bugs, cleaning up code, introducing new content and/or features; see [https://github.com/pioneerspacesim/pioneer/blob/master/Changelog.txt Changelog.txt]. All contributors work on pioneer for free when they have time and motivation.

=== What's the deal with the inconsistent UI interface? ===
Pioneer started as a pure Frontier clone in 2008, with UI closely matching that game, implemented in pure C++. This UI is referred to, by the developers, as "OldUI".

Pioneer started transitioning to a "NewUI" defined in easy-to-change Lua files ([https://github.com/pioneerspacesim/pioneer/pull/2589 #2589], merged in 2013), that do not require recompilation, thus ideal for users to play around with, extend and ideally contribute any improvements back into the project.

Due to lack of time, and coders, transition stalled, with SystemInfo being halfway there ([https://github.com/pioneerspacesim/pioneer/pull/3564 #3564]). At the time of writing this the SectorView (F2) and OrbitView (F6), and others are still defined in the old hard coded C++ source code.

In the summer of 2016 work started to move Pioneer to a [https://github.com/ocornut/imgui dear-imgui] based UI, which developers call "PiGUI", starting with a new, and vastly improved HUD, with instrumentation that should be familiar to players of Kerbal Spaceprogram, for manually executing orbit manoeuvres. Thus at this moment Pioneer had three UI systems at once: OldUI, NewUI and PiGui.

Update 2021-01-01: We have now killed off NewUI completely, and much of OldUI: [https://github.com/pioneerspacesim/pioneer/pull/5032 #5032], in favour of PiGui, which is much easier to script in. Thus we could be said to only be using 1.1 UI systems.

In the transition to PiGui, the galaxy (image) map (F8) was removed, since motivation in the dev team to purge the code base of NewUI right away was higher than to port it to PiGui, as it didn't have any real purpose for the game, other than as a fun gimmick. (The galaxy image is still used under the hood to compute star density in sectors)

=== Do you accept contributions? ===

Hell yes! Pioneer is not any one persons personal project. It is the sum of the contributions made by the people who play and care about the continued development of the game. See: [[How_you_can_contribute|How to contribute]].

User:Sturnclaw

2020-10-21T20:35:59Z

Sturnclaw: Update THE LIST

Hello! My name is Sturnclaw. Your code offends me. Prepare to die.

In more serious news, I'm known as Sturnclaw around here. In demeanor, I'm pretty much your typical overconfident software engineer who thinks he can do anything given enough time and sauerkraut – I'll leave the verification of that claim up to the reader.

A cursory search will reveal that I'm the owner and head of Web eWorks, LTD, and when I'm not busy with that or one of a number of side projects, I work on Pioneer to brush up my C++ skills.

You can find me on Github as [https://github.com/web-eworks Web eWorks], or on IRC as sturnclaw.

== The List ==

Upon the recommendation of several members of the team, I have begun to curate The List, stored right here on this page.

What is "The List", you ask? The List is basically a copy of Pioneer's roadmap, kept fairly current to the latest IRC <s>fantasizing</s> plans, and annotated with my thoughts and recommendations for implementation. It is estimated that completing all of the items on The List will take between 5 and 15 person-years of development work, so if you want to implement something here, go right ahead.

Without further ado, I present The List:

=== Core Tech: ===

==== Entity Component System (ECS) Model ====
Convert the Pioneer codebase to use a composition-based model instead of an inheritance-based model.
* The rationale behind this decision is that an inheritance-based architecture for gameplay objects is generally unsustainable without some form of composition, especially so when mods are involved - what if your mod wants to add a different implementation of a hyperdrive?
* This will be a multi-step process:
** Implement some minor features using the ECS paradigm to get started and evaluate requirements. '''Working'''
** Drive the new ECS-based features from existing code as a temporary measure. '''Working'''
** Convert a major feature (Ship, BodyOnPlanet, etc) to use the ECS.
** Continue converting major features until all applicable areas of the code are converted.

==== Input System ====
Before I started working on Pioneer, the input system was particularly archaic; inputs were defined with macros in a single file that got <nowiki>#include</nowiki>d into about 4 different files and compiled into the binary - needless to say, if you wanted a new input axis or action, you had to recompile the entire game.

The input system is currently being refactored into a modular, moddable system which supports sharing axes between systems and modules and defining entirely new axes and actions in mods.

This change is about half done - the technical underpinnings of the system are mostly finished, and all that's left is to expose it to Lua.

Planned Features:
* Modular, Lua-exposed input system '''WORKING'''
* Key-chord inputs, allowing arbitrary modifier keys / buttons. A software "pinkie switch" if you will. '''DONE'''
* Frame-based input grouping system, allowing multiple conflicting "modes" to be enabled or disabled en-bloc. '''DONE'''
* Touchscreen input for camera and flight controls. (Investigate: virtual joysticks or whole-screen mouse emulation?)

==== Model System ====
The model system needs further work and refactoring. It currently bloats savefiles excessively, has a very limited API that ignores file paths, is a pain to build files for release builds, and cannot be multi-threaded.

Planned Improvements:
* Don't store a list of transform visitors in savefiles; animations should be responsible for node positioning. Possibly use a dirty flag to only store nodes that have been explicitly positioned by code?
* Refactor all code and data that touches models to use full paths instead of just the basename component.
* Refactor model loading to make it asynchronous; run the load step on a separate thread, and add an end-of-frame task on the main thread to upload model data to GPU
* Allow ModelBody to cache collision objects. This will likely come hand in hand with not creating separate Model instances.

==== Lua Engine ====
Coming on the heels of the input changes are improvements to Pioneer's Lua engine. At current, Pioneer is using its own feature-incomplete version of <nowiki>require()</nowiki> (used as <nowiki>import()</nowiki>), which supports a very limited method of calling other code files. Additionally, the C++ side of the Lua interface has issues with handling Lua errors - if C++ calls a lua function that errors, the whole engine terminates with an error.

There are several goals to accomplish here, but the major two are:
* Update <nowiki>import()</nowiki> to support Lua 5.2+ style "module.submodule" syntax and implicit "init.lua" support. '''DONE'''
* Deprecate <nowiki>import()</nowiki> in favor of <nowiki>require()</nowiki> to support languages that target Lua. '''DONE'''
* Make throwing a Lua error safe with regards to C++ code, and support arbitrarily disabling a Lua module if it is throwing an error.
** E.g. if a specific part of the UI throws an error, silently catch it and log it. If it keeps throwing errors, disable the module and inform the user. This is going to require some significant work, but it will make the modding and content-creation ecosystem much more user-friendly.

Tangentially to the ECS changes, we need a better method of binding C++ code and data to Lua. Currently the hand-written method is serviceable, but it is akin to "implementing the same thing twice", doubling the workload for anyone wanting to add something new.
* Add an automatic solution for binding C++ code to Lua, capable of auto-generating bindings for properties, methods, and POD-structs and full LuaObject classes. '''DONE''' (see LuaMetaType.h)

=== Gameplay: ===

There are a ''huge'' number of new features and wild gameplay ideas that I and others would really like to see added to the game, but this is a more reasonable list of features that can actually be implemented with a few weeks of work.

* Refactor the camera / view system to better support inputs, allow arbitrary spectator / debug cameras for editor mode, enable first-person and turret cameras. '''WORKING'''
** Add a "camera offset" axis for internal / cockpit view that can be hooked up to headtracking. '''DONE'''
** Make the existing camera system use the new InputFrames for input. '''DONE'''
** Decouple camera systems from the concept of a ship to make them suitable for debug/flying cameras. '''WORKING'''
** Add cameras for turrets.
* Completely rewrite the weapons systems to support arbitrary guns and turrets, as well as a better loadout system.
* Rework drag and atmospheric heating to be actually accurate. '''WORKING'''
* Implement atmospheric lift so aerodynamic ships can fly. '''DONE'''
* Add airframe damage due to excessive G-force and/or dynamic pressure when flying in atmosphere.
** Possibly damage specific components (landing gear, control surfaces, etc) reducing their effectiveness and/or destroying them.

=== Rendering: ===

==== PBR Rendering Engine ====

Convert Pioneer to a Clustered Forward or Clustered Deferred rendering model. This change needs to implement support for numerous lights, mesh decals ala Star Citizen, accurate terrain rendering with high-res texturing support via material layering and distance-dependent detail texturing, a full postprocessing chain including bloom, chromatic aberration, motion blur, and an AO implementation (perhaps an HBAO or SSAO variant), support for atmospheric shading, etc.

Reference:
* [https://turanszkij.wordpress.com/2017/10/12/forward-decal-rendering/ Forward+ Decal Rendering]
* [https://google.github.io/filament/Filament.md.html Filament Renderer], an open-source mobile-capable Clustered Forward PBR renderer, with accompanying whitepaper.
* [http://www.cse.chalmers.se/~uffe/clustered_shading_preprint.pdf A paper on clustered rendering]
* [http://www.thetenthplanet.de/archives/4519 Atmospheric Scattering] with link to implementation.

'''Clouds'''

Possibly using a low-resolution voxelized implementation, atmospheric clouds are a planned feature. They'd need to support transparency, layer over each other without killing performance, and look at least moderately good. Flat clouds are also required when looking at a planet from orbit, which could be static textures or generated from a basic weather simulation for believable construction.

''' Mesh Decals '''

TODO: link in nozmajner's ship decal work, pontificate about supporting that engine-side.

=== Content: ===

* Finish modelling and texturing the Sador Heavy Fighter, including setting it up to use turrets and a new gun / missile system.

Using git and GitHub

2020-09-28T17:25:58Z

Sturnclaw: /* Fixing/Updating your pull request */

Developing on pioneer means using the version control tool 'git' and the [https://github.com/ github] website. git especially has a reputation for having a steep learning curve, so here we'll try to give you enough knowledge to be dangerous!

== Prerequisites ==

A working installation of git, a GitHub account, and comfort with using the command line of your chosen operating system.

The GitHub sign-up page is [https://github.com/signup/free here]. Make a note of your user name as you'll need it to make your local pioneer repository.

On Linux, git is available in all distributions using the standard tools such as APT, yum or emerge. Since there is a wide range of file browsers and graphical environments, this tutorial limits itself to the command line interface.

On Windows you have two options, [http://msysgit.github.com/ Git for Windows] aka msysgit, or [http://windows.github.com/ Github for Windows] which is essentially msysgit but with some extra stuff bundled. Some of which is good ([https://github.com/dahlbyk/posh-git posh git]) and some of which is well, not (github's 'friendly' gui). Since both include the same command line tools and cross platform gui tools, either is fine for our purposes here. The github one may be more convenient to install.

On Mac OS X, git will have been installed with XCode as git is built into the XCode IDE. However, usage of git from from within an IDE isn't something I'm familiar with so isn't covered here. If you want to follow along with this document then if you elected to install the XCode command line tools, then the git commands below should work unaltered from a terminal window. If you didn't then you'll need to use <code>xcrun</code> to run the commands in terminal, either by adding <code>xcrun</code> in front of each of the commands or aliasing <code>git</code> and <code>gitk</code> to <code>xcrun git</code> and <code>xcrun gitk</code> in your <code>~/.profile</code>. Have a look at [http://www.cocoanetics.com/2012/07/you-dont-need-the-xcode-command-line-tools/ this guide] for details.

A clear and concrete introduction to git can be seen at this [https://rogerdudler.github.io/git-guide/ Git Guide]

=== Configure git to sane global settings ===

First we need to [http://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration configure] git some. You probably want to run these commands:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global color.ui true
git config --global push.default simple

Note, that each commit you do will be stamped by your name and email entered here.

Also, in our [[Coding Conventions]] we use 4 width tab indentation, but the "git diff" and "git show" tools assume 8 character wide tabs. This is fixed by:

git config --global core.pager 'less -x1,5'

(the cryptic numbers are due to git using the first column for "+"/"-" to show inserted or removed lines)

== Creating your pioneer repositories ==

Git, as a version control system, stores all source files for Pioneer (or any other project you've chosen to manage with git) along with their histories in '''repositories''' (usually shortened to just 'repos'). These are areas of a computer's file system where has git has been told to track and manage changes to the files placed in them.

There are three different repositories that you mainly deal with when developing pioneer.

*The <code>upstream</code> repo. This is the main Pioneer repository stored on GitHub. This is read-only except to the core team (and even they don't do their development there).
*The <code>origin</code> repo. This is a public Pioneer repository personal to you, but stored on GitHub under your username, so other people can see the changes put into it. This is read-only to everyone except you.
*The <code>local</code> repo. This is your personal Pioneer repository on your computer, not accessible by anyone else.

Before you can start developing you need to setup both your Pioneer <code>origin</code> and <code>local</code> repositories.

=== Your origin repository ===

Your <code>origin</code> repository you make on GitHub. To do that, make sure that you're logged in there and go to the main [https://github.com/pioneerspacesim/pioneer GitHub Pioneer page] in your web browser, and click the 'Fork' button at the top of that page: [[File:ForkPioneer.png|RTENOTITLE]]

GitHub will clank and whirr as it makes a copy of the main Pioneer repo under your username. Eventually it will finish, and you'll end up on page almost exactly like the main GitHub Pioneer page, but instead of being named <code>pioneerspacesim/pioneer</code> your copy is named <code><your github user name>/pioneer</code>.

Having made your <code>origin</code> repo, you're now ready to make your local one.

=== Your local repository ===

You make your <code>local</code> repository by cloning a copy of your new <code>origin</code> repository to your local machine.

At the command line, navigate to where on your filesystem you want to put your local git repos. For instance on Linux I put mine in <code>~/repos</code> whilst on Windows I put them in <code>c:\develop\github-repos</code>. You can move the folder at a later time without breaking anything. Once you're there execute the following command replacing <code>your github username</code> with, well, your github username.

git clone [git://github.com/your https://github.com/your][https://github.com/your%20gituhub%20username/pioneer.git gituhub username/pioneer.git]

Just like clicking Fork on the main Pioneer GitHub repo made a clone of it under your GitHub account, this makes a clone of that clone to your local machine. Expect this to take some time, just like before, as it copies all the files and the complete history of the project to your filesystem, only now it's sucking the data from GitHub to your machine, rather than copying things around within GitHub's data centre (so it will probably take even longer; however, a modern coputer does it on the order of minutes).

Eventually this operation will complete, and you'll have a shiny new directory named <code>pioneer</code> which git -- with a little encouragement -- will manage for you, your <code>local</code> repo.

We're almost done with repository setup, but there is one more thing we need to attend to. When you did <code>git clone</code>, it automatically set <code>origin</code> to point to your Pioneer repository on GitHub. However it didn't set <code>upstream</code> to point the main Pioneer Repository. We'll need to do that manually.

We must to be inside the repository to do this, in fact all the git commands from now on, you need to be inside a repository to execute any of the git commands shown. So enter the pioneer repository directory, before doing:

git remote add upstream [git://github.com/pioneerspacesim/pioneer.git git://github.com/pioneerspacesim/pioneer.git]

...to define <code>upstream</code> as the main Pioneer repository. You'll notice you defined <code>upstream</code> as a <code>remote</code>, <code>origin</code> is also defined as a <code>remote</code>. We'll explain more about remotes later on.

You can now view the result of our commands, i.e. see how we link the <code>origin</code> to your git repo, and upstream to the central pioneer repository.

git remote -v

or for more details

git remote show origin

== Basic operations ==

At this point you might want to consider searching for tutorials. There are many good ones on git out there. If you're familiar with svn look [http://git.or.cz/course/svn.html here], and [http://marklodato.github.io/visual-git-guide/index-en.html this] is a nice visual representation of different commands, which might be helpful. Basic git tutorials on youtube: [https://www.youtube.com/watch?v=vaNGbk6HN9Y part 0], [https://www.youtube.com/watch?v=DQUcmNO4diQ part 1]. Below follows a few commands you will be using a lot, and be familiar with, but first make sure to delve into some tutorials. Git is a vast subject.

Show documentation of command

git help <command>

Create branch...

git branch <branch-name>

...and move into it:

git checkout <branch-name>

Or do both in one go

git checkout -b <branch-name>

Check what files have been changed (red), and which have been staged for commit (green)

git status

Add new or changed/modified file to be "staged"

git add <file>

and commit it (sometimes it's good to check "git status" first, to see what is staged)

git commit

Or do it all in one go (this will not add new files, just changed, already tracked files)

git commit -a

or

git commit -am "This is my commit message"

The two above commands (i.e. "git commit -a") will commit all changes seen when running the highly useful

git diff

=== Show information ===

Investigating what you've done is always very useful, and instructive when learning git. To show your un-staged changes (changes not staged for commit)

git diff

One of the most used commands might be to list the commit history

git log
git log -p <file>
git log --oneline --graph

and

git show HEAD
git show <commit>

Or N commits back in history

git show HEAD~<N>

List local branches

git branch

List local branches, and show last commit on each

git branch -v

List local and remote (origin) branches, and show last commit on each

git branch -va

This is a nice graphical interface to git, that you might prefer

gitk

=== Common fixes for mistakes ===

Here we outline highly useful knowledge for fixing very common mistakes or situations you will find often yourself in.

It's common to want to add/change or reword the last commit, simply <code>git add</code> if any changes and

git commit --amend

If you realize you did <code>git add</code> on a file that should not be included in the commit you are about to do, then un-stage it by:

git reset HEAD

If you need to undo a commit you have already made simply reset the branch to one step back

git reset HEAD~

or equivalently

git reset HEAD~1

These reset commands only operates on the git record, not removing any changed files from your hard drive.

If you already pushed the old commit to <code>origin</code> (your github), then you need to do a forced push

git push -f origin

== Updating your branches ==

Makes no changes on your local copy, but reads in what changes there are upstream. A safe command.

git fetch upstream

Or read in changes in all branches, and <code>-p</code> to purge, i.e. remove the lingering memory of branches that have been removed in origin

git fetch --all -p

Now we know what changes have been made to <code>upstream</code>, i.e. Pioneer space sims's master branch. Now to apply them to your master

git checkout master
git merge upstream/master

Which is the same as

git pull upstream master

Now, your local master (on your HDD) is synced with upstream (Pioneer's), but you probably want to update your github, <code>origin</code>, master branch as well:

git push origin master

=== Doing a hard reset ===

If you feel you've messed up your master branch, and just want to "start over", or get a clean copy from upstream Pioneer, you can do a hard reset. However, be ware that this is a dangerous command, as it will remove any changes on the branch it is run from and make it identical to whatever you reset it to.

git checkout master
git fetch --all
git reset --hard upstream/hard

or if you want to reset your branch <code>my-branch</code> to how it looks in your github

git reset --hard origin/my-branch

Next, since a hard reset completely rewrites the commit history, when you push your updated master (or whatever branch), to origin, it might say that the two branches have conflicting history, thus you need to force push your fresh copy

git push -f origin master

== Pushing branch (smart way) ==

Normally to push your commit to your github, you might do:

git push origin <branch name>

However, it would be nice if your branch on your local git (on your HDD) and your origin (your github) know about each other, that they are the same. Luckily git allows this, by "tracking" the branch thus, typically the first time you push commits in your local branch to github you tell github to track it

git push --set-upstream origin <branch name>

Or shorter

git push origin <branch name> -u

Now, whenever you do the following commands from a tracked branch

git push

or

git pull

it will be from your local <branch-foo> to its remote copy on origin (github). Also, git will show which branch is ahead of which

git branch -vva

== Resolving Conflicts ==

Conflicts happen when git tries to apply a commit and that commit changes code on the same or neighboring lines of code as some other commit that it's trying to merge with. Typically this can happen when issuing commands such as <code>cherry-pick</code>, <code>rebase</code>, or <code>merge</code>. Once you get the hang of it, they're easy to resolve. Just read the error message git spits out, and run

git status

It will show some files that need to be manually edited. In the file it will show both versions of the lines conflicting. Edit the file to the way it should be then <code>git add <file></code> and then <code>git commit</code>.

== Making a pull request ==

Make a branch, push it to your Github repository, and you will get a "Compare / Open Pull Request" button when viewing your branch on your Github account if logged in. Press it, and write a description of the changes you've made. Mention what improves by the changes made in the pull request. (For more, see github documentat [https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork here]).

== Fixing/Updating your pull request ==

This addresses the case where you have opened a pull request on Github, only to realize (by yourself, or through a reviewer giving feedback) that you need to change something. Conveniently, Github tracks your branch so any change to it will also update the commits in your pull request.

For example, you make some new change to your branch, add and commit them:

git commit -am "this is an additional commit"

Then just push it to your branch:

git push

(Note: this assumes your local branch is set up to track your Github branch)

However, doing it like this is only recommended if the new commit actually adds something new to the branch, where it is logical to have it as a separate commit. If it is a bug fix for a previous commit in the same pull request, there is no need for us to see it in the master branch of pioneer once it is merged. Thus the following two subsections describe how to fix the commit log / history.

=== Update / change last commit ===

The first case is the simplest: if you just want to change the last commit in your branch, because you realized some file was missing, or needed an edit.

Make your change, then run "git add" on the changed files. Now update the last commit by:

git add <changed_file>
git commit --amend

And push to your Github, but since the hash id of the last commit has changed, you need to force it

git push -f

Done.

Note this also lets you reword the commit message.

=== Update / change commit in middle of the branch of the pull request ===

The second case covers if you need to edit commits further back in the commit history, or change order of commits or any other change.

The example case we use here has a git log looking like so:

git log --oneline
dd34lqe added final feature D
cc5369b added third feature C
bb1ed97 added second feature B
a528f11 added initial feature A

Now you want to fix a bug in your second commit for feature "B". Make your changes in your local branch, add them and commit. Your structure will now look like:

git log --oneline
98a9832 my bugfix for feature B
dd34lqe added final feature D
cc5369b added third feature C
bb1ed97 added second feature B
a528f11 added initial feature A

The bug fix commit is redundant to see in the git log once in master, so we want to merge the bug fix commit with "bb1ed97 my second feature B" commit, so that ''no one will ever know there was a bug in the first place''! You do this by "rebasing" your branch.

git rebase -i a528f11

This opens the rebase dialogue in your default editor for git (usually vim, emacs, or nano). It will show you the git history for all commits after (i.e. excluding) the commit a528f11 ("added initial feature A").

You will see in the editor something like this (don't be confused by the reverse order compared to git log command):

pick bb1ed97 added second feature B
pick cc5369b added third feature C
pick dd34lqe added final feature D
pick 98a9832 my bugfix for feature B

# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out

Now just move the last line to be just below the commit we want it to fix, and mark it as a "fixup", which will merge it into the commit above it, and use its commit message:

pick bb1ed97 added second feature B
fixup 98a9832 my bugfix for feature B
pick cc5369b added third feature C
pick dd34lqe added final feature D

Save, and quit, and hopefully git will report that the rebase was successful, and your git history will now be clean, but the commit hash (and code) for the "B feature" has changed, thus we need to force push the change to Github.

git log --oneline
dd34lqe added final feature D
cc5369b added third feature C
qq9860d added second feature B
a528f11 added initial feature A

git push -f

(again assuming your local branch is tracking the Github repo)

=== Resolving Merge Conflicts ===

Sometimes while you're working on a Pull Request other code will be merged into master that touches a file you've been working on. 90% of the time there's nothing you need to do, but occasionally git can't simply resolve the two changes and you'll need to manually update your code.

The easiest way to update your branch with the changes from master is called a "merge commit", where you merge in the changes from master to your local branch. '''DON'T DO THIS'''. It creates a messy history and makes it extremely difficult to review your pull request, as there's now two copies of those changes to the master branch.

Instead, please run a git rebase on your local branch to keep the pull request changes small and ensure it can be easily merged:

git fetch upstream master
git rebase -i master

== Getting other developer's branches ==

If you want to get a copy of a branch from another developer, be that to test it, or to <code>cherry-pick</code> (covered elsewhere) commits into your own branch.

First make a branch from your master, and jump into it. It can be named whatever.

git checkout -b <branch-name> master

Now pull the code in from the developer's branch named <code><dev-branch></code>

git pull https://github.com/<developer-user-name>/pioneer.git <dev-branch>

If it's a developer you will often want to pull code from you can add him/her to your remote, just like you did with your own github <code>origin</code> and Pioneer's <code>upstream</code>.

git remote -v

add a new one, named <code><remote></code>.

git remote add <remote> <url>
git remote update
git checkout -b <branch-name> --track <remote>/<remote-branch-name>

== Keeping things tidy ==

If branch is merged into master then it can safely be deleted

git branch -d <branch-name>

If branch is not in master, then a force remove can be made

git branch -D <branch-name>

git push origin :<branch-name>

git clean -n

git clean -f

== Cherry picking ==

If wanting a commit from someone else, e.g. to add to your own branch, you can pull down their branch to your machine, then from the branch you want it to, just do:

git cherry-pick <commit-hash>

To actually do the "pulling down" of their branch to your machine:
<pre>git remote add dev-username git://path/to/dev-username/repo.git
git fetch dev-username</pre>

You might also be inetersted in following future changes in dev-username's branch:
<pre>git checkout --track dev-username/foo</pre>

Also, another useful tool, for those graphically inclined is:

gitk

'''Warning''': cherry picking, although sometimes useful, can cause problems for other developers if you use them on commits that have already been published to github. Be careful and give sufficient warnings if you find you needing to use them in that situation.

== Pushing to upstream Pioneer master ==

So you have working knowledge of git, and have been deemed not (too) crazy to be given commit access to the pioneer source? Welcome! As this means you can merge your own -- and others -- code into pioneer master, there are a few things you might want to know.

=== Guidelines for merge etiquette ===

The power to merge code on to a common code base requires mutual respect among the developers, and [https://en.wikipedia.org/wiki/Fingerspitzengefühl fingerspitzengefühl] based on the knowledge they have of each other, such as what their typical response time is, and where their area of expertise, and (code) interest/disinterests lies. If these principles were put into writing they might look something like the following:

*You still need to open pull requests (PR), and hold them open long enough for other developers to have a fair chance to have time to voice their opinion, and possibly/occasionally review it. Don't count on the latter though, you're responsible for what you break, and you are now expected to review your own code.

*An instant merge of a PR can be done from time to time when the change is trivial, and obviously "good", and/or working on code that is "your private realm" of the pioneer source, and/or when you or other person needs a feature in master as soon as possible, for the next build.

*Also, you may push a commit directly to master, with no PR, if the change is ''very'' trivial one-liner, for instance fixing a very silly error in just merged code.

*You may ''not'' ever do a forced push to pioneer master.

=== How to merge a PR the proper/pedantic way ===

For those with push access to https://github.com/pioneerspacesim/pioneer this is one way to push code to master. First make sure you have a resonable setup:

git remote -v
origin https://github.com/myusername/pioneer.git (fetch)
origin https://github.com/myusername/pioneer.git (push)
upstream https://github.com/pioneerspacesim/pioneer.git (fetch)
upstream https://github.com/pioneerspacesim/pioneer.git (push)

Also, it might be a god idea to clean your master branch, so you know it is identical to pioneer upstream, but do be warned, this will wipe your master branch, thus if you have commits that are not in their own branches, they will be lost (but retrievable through git reflog):

git checkout master
git reset --hard upstream/master

(For future merges, a simple git pull will suffice, if you've kept your master branch clean)

Now get the branch from the contributor to your computer, by creating an aptly named branch, and then pulling the code from the contributor to this branch.

git checkout -b name_of_branch_to_create
git pull https://github.com/contributor_username/pioneer.git name_of_branch_user_has

Now switch to your master, and merge it in, here we asume the branch you created was called "feature_branch"

git checkout master
git merge --no-commit --no-ff feature_branch

Document changes to Changelog.txt, then add it, so from the pioneer root folder, the path to Changelog wold just be:

git add Changelog.txt
git commit

This has now included the Changelog edit into the merge commit. Now do a dry run:

git push upstream master --dry-run

Check that the right commits will be pushed with

git log

And let us do it for real this time:

git push upstream master

Please note: NEVER do a force push to pioneer master!

== Advanced ==

Collecting some advanced tricks for developers

=== Push commit to someones PR ===

If you have push access to pioneer repo, then you also have push access to other contributor's pull requests.

Get the user's PR into a branch as usual:

git checkout -b some_user-feature_branch master
git pull https://github.com/some_user/pioneer.git feature_branch

make your changes, now push:

git push https://github.com/some_user/pioneer.git some_user-feature_branch:feature_branch

=== PR trick ===

For developers, or anyone interested, this trick will pull down all the pull requests from github, so you can easily switch to pull request, say, #1234 by doing

git checkout refs/pull/upstream/1234

=== Be a git pedantic? ===
Writing good [https://github.com/RomuloOliveira/commit-messages-guide commit messages], and being pedantic has its values.

== Links and resources ==
* [https://github.com/k88hudson/git-flight-rules git-flight-rules] Lots of examples, and links to further resources
* [https://ohshitgit.com/ Oh shit, git!] Fixing common mistakes in git
* [https://git-rebase.io/ git rebase in depth] Good guide on how to clean up/fix your git commit history

Code style

2020-05-11T02:46:11Z

Sturnclaw: Remove obsolete Code Style page (merged with Coding Conventions)

#REDIRECT [[Coding Conventions]]

This page has been merged with [[Coding Conventions]].

Commit access

2020-05-11T02:43:19Z

Sturnclaw:

== What is commit access? ==

Having commit access means you have the ability to push code directly to the main Pioneer repository.

== How do I get commit access? ==

Usually, just by asking. If you're known to the other committers to be someone who can be trusted to be a good steward of the project (usually shown by the quality of previous contributions) then you'll be given access to push to the repository. This is deliberately a subjective measure, but rest assured, the bar is set pretty low. Its mostly just a check to make sure you aren't going to do something stupid.

In some circumstances you might be offered commit access. The same bar is set there. It usually happens when the other committers finds themselves thinking "this person would be a good committer".

== What do I need to know when pushing? ==

There's a few things that are special to the way we work that you need to know about.

=== Code style ===

We have a [[Coding Conventions]] style guide. Learn it, love it. There's almost certainly something in there you'll hate, because we all have different opions on code style. Don't argue, just use it - its what we've got!

=== Code review ===

Read the page about the [[Code_review|code review process]]. You're expected to be reviewing your own code according to the guildlines set out there, and you're encouraged to find another person to review your code if its particularly large or complex. Read that page for more info about that.

There is no obligation for commiters to review other people's work, but it would be very helpful if you could. If everyone is involved, then the total workload on any individual remains small, giving everyone time to work on their code.

=== Update the changelog ===

[https://github.com/pioneerspacesim/pioneer/blob/master/Changelog.txt Changelog.txt] is where we track the history of the project. Each time you make a change, add a brief description of it to the Changelog. Include the Github issue or pull request number if it has one. The description should be something that is understandable by players. Choose an appropriate category, start a new month header at the start of the month, and preserve the existing formatting. Have a look through the history to get a feel for how it works.

=== Don't break the build ===

Pioneer is regularly built by an autobuild script, sometimes as often as once per day. This is done using the Makefile/autotools system (all platforms). You must take care to ensure that everything that lands on the master branch builds correctly with the autotools/GCC build. This could be a problem for Windows-based developers using MSVC; please do the best you can and ask for help if you need it.

=== Don't change existing git history ===

Once a commit is in the master repository, it must stay there: You must never force-push. That means, never use the -f or --force switch to the 'git push' command when you're pushing to the pioneerspacesim repository. If you're getting an error when you push, ask for help, because forcing things is a guaranteed way to break the repository for everyone.

Code review

2020-05-11T02:42:57Z

Sturnclaw:

== Why do code review? ==

Code review is simply getting someone to check your code before you it gets included in the Pioneer code proper to make sure that the code is of a good quality, is consistent with the rest of the codebase and takes Pioneer in the direction that the community wants it to go.

== When does it happen? ==

Code review can happen at any time, whenever you like. For small items of work it will get at least one review when it is submitted for inclusion (via a pull request). For a large development you may wish to find to someone to review your code periodically, to make sure you're on the right track. If you're starting to feel a bit unsure about what you're doing, that's probably a good time to ask someone!

You don't have to do this of course, but be aware that the reviewers don't particularly being asked to review hundreds or thousands of lines of code changes that appear out of nowhere. You face a good chance of having your code rejected outright or ignored completely, and that sucks. So if you're going to do something massive, at least check in at the start to make sure someone knows about it.

== Who can review code? ==

Anyone that wants to! Anyone can use the review tools on Github to read and comment on code while its under development or test pull requests.

In the case of a pull request, someone with commit access needs to do the final sign-off (typically, but not necessarily, at the same time as merging). If you don't have commit access you can still help make life easier for that person by leaving comments and working with the original submitter.

== I have commit access, does my code need to be reviewed? ==

No, you have commit access for a reason - you've proven that you can be trusted to be a good steward for the project. You should feel free to change whatever you want or need to, but as you do you should be considering all the points normally covered by a review. Self-review, if you like.

That said, no person is an island. Be sure to ask for help if you need it, even if its just a feeling that something isn't right.

== What gets reviewed? ==

Every single change is a candidate for review, no matter how small. Most review will happen in a pull request, but you can be reviewing code by reading the commit history or even by reading code as you're working on it.

Here are some good things to look out for:

* Bugs, logical errors, mathematical errors, typos (any simple, isolated code error). These are easy. If you find a bug during testing or by looking at the code, either fix it or tell the submitter to fix it. It's easy because everyone agrees that bugs need to be fixed.

* Uncertainty about some code logic or behaviour ("Is this maths right?" "Did the submitter intend this weird behaviour?"). These are easy: Ask the submitter (obviously). Explanatory comments are usually the "fix" here.

* Code style errors (braces, whitespace, naming conventions, etc). Same as bugs: fix it, or tell the submitter fix it. Not everyone agrees about the importance of code style, or perhaps even what style we should be using (particularly since the existing codebase is not totally consistent), but we have a [[Coding Conventions]] guide and we want everything to conform to it. If there is some aspect of style not covered by the code style guide on the wiki, amend the guide and tell the submitter to fix their style. Yes, style is subjective, and it's not the submitter's fault that they didn't use the "correct" style, since it may not have been clear what was the "correct" style when they made the PR, but its not worth arguing about - the time and energy to discuss it costs more than just fixing the code.

* Messy git history. Fix it or ignore it. The trouble with telling the submitter to fix it is that many of our contributors don't have enough confidence wth git to do it right and the ones that do tend not to submit messy histories in the first place. So its not worth arguing about. Just do the best you can to keep your own history tidy, but if its not working out don't stress too much about. If you really need help, talk to someone that can drive Git well; they can help you out.

* Game design uncertainty ("Do we want this feature?", "Do we want it to behave this way?"). For the most part you should choose what you think is best. You should be paying attention to what the other developers and the players are asking for and be aware of what other developments are happening, and from there be able to make a reasonable decision. If you don't know, ask someone who does. But remember that you should not reject an idea simply because you prefer it a different way. Of course your opinion matters, but try to balance everyone's needs as much as possible. (This is hard. Please ask for help).

* Code structure problems ("We want the feature, but not implemented like this"). Structural problems can take a significant effort to fix and they make future code maintenance harder. They're the ones that often end up needing to be ripped out or rewritten later. The difficulty is that its often a ridiculous amount of effort to do something the "right" way, especially if it relates to a very old piece of code. The rule of thumb then is to permit mess if its necessary, but do the best you can to keep it contained. Remember that you're now adding to the cleanup work that someone else will have to do in the future.

== Merging looks hard, do I have to? ==

No. You can still review code without having to do the merge yourself. If you're not confident enough with git to do the merge properly, please ask someone who can. Mention that your code review is done and you're happy with it and they will merge it without any fuss.

Using git and GitHub

2020-05-11T02:42:29Z

Sturnclaw: Update links

Developing on pioneer means using the version control tool 'git' and the [https://github.com/ github] website. git especially has a reputation for having a steep learning curve, so here we'll try to give you enough knowledge to be dangerous!

== Prerequisites ==

A working installation of git, a GitHub account, and comfort with using the command line of your chosen operating system.

The GitHub sign-up page is [https://github.com/signup/free here]. Make a note of your user name as you'll need it to make your local pioneer repository.

On Linux, git is available in all distributions using the standard tools such as APT, yum or emerge. Since there is a wide range of file browsers and graphical environments, this tutorial limits itself to the command line interface.

On Windows you have two options, [http://msysgit.github.com/ Git for Windows] aka msysgit, or [http://windows.github.com/ Github for Windows] which is essentially msysgit but with some extra stuff bundled. Some of which is good ([https://github.com/dahlbyk/posh-git posh git]) and some of which is well, not (github's 'friendly' gui). Since both include the same command line tools and cross platform gui tools, either is fine for our purposes here. The github one may be more convenient to install.

On Mac OS X, git will have been installed with XCode as git is built into the XCode IDE. However, usage of git from from within an IDE isn't something I'm familiar with so isn't covered here. If you want to follow along with this document then if you elected to install the XCode command line tools, then the git commands below should work unaltered from a terminal window. If you didn't then you'll need to use <code>xcrun</code> to run the commands in terminal, either by adding <code>xcrun</code> in front of each of the commands or aliasing <code>git</code> and <code>gitk</code> to <code>xcrun git</code> and <code>xcrun gitk</code> in your <code>~/.profile</code>. Have a look at [http://www.cocoanetics.com/2012/07/you-dont-need-the-xcode-command-line-tools/ this guide] for details.

A clear and concrete introduction to git can be seen at this [https://rogerdudler.github.io/git-guide/ Git Guide]

=== Configure git to sane global settings ===

First we need to [http://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration configure] git some. You probably want to run these commands:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global color.ui true
git config --global push.default simple

Note, that each commit you do will be stamped by your name and email entered here.

Also, in our [[Coding Conventions]] we use 4 width tab indentation, but the "git diff" and "git show" tools assume 8 character wide tabs. This is fixed by:

git config --global core.pager 'less -x1,5'

(the cryptic numbers are due to git using the first column for "+"/"-" to show inserted or removed lines)

== Creating your pioneer repositories ==

Git, as a version control system, stores all source files for Pioneer (or any other project you've chosen to manage with git) along with their histories in '''repositories''' (usually shortened to just 'repos'). These are areas of a computer's file system where has git has been told to track and manage changes to the files placed in them.

There are three different repositories that you mainly deal with when developing pioneer.

*The <code>upstream</code> repo. This is the main Pioneer repository stored on GitHub. This is read-only except to the core team (and even they don't do their development there).
*The <code>origin</code> repo. This is a public Pioneer repository personal to you, but stored on GitHub under your username, so other people can see the changes put into it. This is read-only to everyone except you.
*The <code>local</code> repo. This is your personal Pioneer repository on your computer, not accessible by anyone else.

Before you can start developing you need to setup both your Pioneer <code>origin</code> and <code>local</code> repositories.

=== Your origin repository ===

Your <code>origin</code> repository you make on GitHub. To do that, make sure that you're logged in there and go to the main [https://github.com/pioneerspacesim/pioneer GitHub Pioneer page] in your web browser, and click the 'Fork' button at the top of that page: [[File:ForkPioneer.png|RTENOTITLE]]

GitHub will clank and whirr as it makes a copy of the main Pioneer repo under your username. Eventually it will finish, and you'll end up on page almost exactly like the main GitHub Pioneer page, but instead of being named <code>pioneerspacesim/pioneer</code> your copy is named <code><your github user name>/pioneer</code>.

Having made your <code>origin</code> repo, you're now ready to make your local one.

=== Your local repository ===

You make your <code>local</code> repository by cloning a copy of your new <code>origin</code> repository to your local machine.

At the command line, navigate to where on your filesystem you want to put your local git repos. For instance on Linux I put mine in <code>~/repos</code> whilst on Windows I put them in <code>c:\develop\github-repos</code>. You can move the folder at a later time without breaking anything. Once you're there execute the following command replacing <code>your github username</code> with, well, your github username.

git clone [git://github.com/your https://github.com/your][https://github.com/your%20gituhub%20username/pioneer.git gituhub username/pioneer.git]

Just like clicking Fork on the main Pioneer GitHub repo made a clone of it under your GitHub account, this makes a clone of that clone to your local machine. Expect this to take some time, just like before, as it copies all the files and the complete history of the project to your filesystem, only now it's sucking the data from GitHub to your machine, rather than copying things around within GitHub's data centre (so it will probably take even longer; however, a modern coputer does it on the order of minutes).

Eventually this operation will complete, and you'll have a shiny new directory named <code>pioneer</code> which git -- with a little encouragement -- will manage for you, your <code>local</code> repo.

We're almost done with repository setup, but there is one more thing we need to attend to. When you did <code>git clone</code>, it automatically set <code>origin</code> to point to your Pioneer repository on GitHub. However it didn't set <code>upstream</code> to point the main Pioneer Repository. We'll need to do that manually.

We must to be inside the repository to do this, in fact all the git commands from now on, you need to be inside a repository to execute any of the git commands shown. So enter the pioneer repository directory, before doing:

git remote add upstream [git://github.com/pioneerspacesim/pioneer.git git://github.com/pioneerspacesim/pioneer.git]

...to define <code>upstream</code> as the main Pioneer repository. You'll notice you defined <code>upstream</code> as a <code>remote</code>, <code>origin</code> is also defined as a <code>remote</code>. We'll explain more about remotes later on.

You can now view the result of our commands, i.e. see how we link the <code>origin</code> to your git repo, and upstream to the central pioneer repository.

git remote -v

or for more details

git remote show origin

== Basic operations ==

At this point you might want to consider searching for tutorials. There are many good ones on git out there. If you're familiar with svn look [http://git.or.cz/course/svn.html here], and [http://marklodato.github.io/visual-git-guide/index-en.html this] is a nice visual representation of different commands, which might be helpful. Basic git tutorials on youtube: [https://www.youtube.com/watch?v=vaNGbk6HN9Y part 0], [https://www.youtube.com/watch?v=DQUcmNO4diQ part 1]. Below follows a few commands you will be using a lot, and be familiar with, but first make sure to delve into some tutorials. Git is a vast subject.

Show documentation of command

git help <command>

Create branch...

git branch <branch-name>

...and move into it:

git checkout <branch-name>

Or do both in one go

git checkout -b <branch-name>

Check what files have been changed (red), and which have been staged for commit (green)

git status

Add new or changed/modified file to be "staged"

git add <file>

and commit it (sometimes it's good to check "git status" first, to see what is staged)

git commit

Or do it all in one go (this will not add new files, just changed, already tracked files)

git commit -a

or

git commit -am "This is my commit message"

The two above commands (i.e. "git commit -a") will commit all changes seen when running the highly useful

git diff

=== Show information ===

Investigating what you've done is always very useful, and instructive when learning git. To show your un-staged changes (changes not staged for commit)

git diff

One of the most used commands might be to list the commit history

git log
git log -p <file>
git log --oneline --graph

and

git show HEAD
git show <commit>

Or N commits back in history

git show HEAD~<N>

List local branches

git branch

List local branches, and show last commit on each

git branch -v

List local and remote (origin) branches, and show last commit on each

git branch -va

This is a nice graphical interface to git, that you might prefer

gitk

=== Common fixes for mistakes ===

Here we outline highly useful knowledge for fixing very common mistakes or situations you will find often yourself in.

It's common to want to add/change or reword the last commit, simply <code>git add</code> if any changes and

git commit --amend

If you realize you did <code>git add</code> on a file that should not be included in the commit you are about to do, then un-stage it by:

git reset HEAD

If you need to undo a commit you have already made simply reset the branch to one step back

git reset HEAD~

or equivalently

git reset HEAD~1

These reset commands only operates on the git record, not removing any changed files from your hard drive.

If you already pushed the old commit to <code>origin</code> (your github), then you need to do a forced push

git push -f origin

== Updating your branches ==

Makes no changes on your local copy, but reads in what changes there are upstream. A safe command.

git fetch upstream

Or read in changes in all branches, and <code>-p</code> to purge, i.e. remove the lingering memory of branches that have been removed in origin

git fetch --all -p

Now we know what changes have been made to <code>upstream</code>, i.e. Pioneer space sims's master branch. Now to apply them to your master

git checkout master
git merge upstream/master

Which is the same as

git pull upstream master

Now, your local master (on your HDD) is synced with upstream (Pioneer's), but you probably want to update your github, <code>origin</code>, master branch as well:

git push origin master

=== Doing a hard reset ===

If you feel you've messed up your master branch, and just want to "start over", or get a clean copy from upstream Pioneer, you can do a hard reset. However, be ware that this is a dangerous command, as it will remove any changes on the branch it is run from and make it identical to whatever you reset it to.

git checkout master
git fetch --all
git reset --hard upstream/hard

or if you want to reset your branch <code>my-branch</code> to how it looks in your github

git reset --hard origin/my-branch

Next, since a hard reset completely rewrites the commit history, when you push your updated master (or whatever branch), to origin, it might say that the two branches have conflicting history, thus you need to force push your fresh copy

git push -f origin master

== Pushing branch (smart way) ==

Normally to push your commit to your github, you might do:

git push origin <branch name>

However, it would be nice if your branch on your local git (on your HDD) and your origin (your github) know about each other, that they are the same. Luckily git allows this, by "tracking" the branch thus, typically the first time you push commits in your local branch to github you tell github to track it

git push --set-upstream origin <branch name>

Or shorter

git push origin <branch name> -u

Now, whenever you do the following commands from a tracked branch

git push

or

git pull

it will be from your local <branch-foo> to its remote copy on origin (github). Also, git will show which branch is ahead of which

git branch -vva

== Resolving Conflicts ==

Conflicts happen when git tries to apply a commit and that commit changes code on the same or neighboring lines of code as some other commit that it's trying to merge with. Typically this can happen when issuing commands such as <code>cherry-pick</code>, <code>rebase</code>, or <code>merge</code>. Once you get the hang of it, they're easy to resolve. Just read the error message git spits out, and run

git status

It will show some files that need to be manually edited. In the file it will show both versions of the lines conflicting. Edit the file to the way it should be then <code>git add <file></code> and then <code>git commit</code>.

== Making a pull request ==

Make a branch, push it to your Github repository, and you will get a "Compare / Open Pull Request" button when viewing your branch on your Github account if logged in. Press it, and write a description of the changes you've made. Mention what improves by the changes made in the pull request.

== Fixing/Updating your pull request ==

This addresses the case where you have opened a pull request on Github, only to realize (by yourself, or through a reviewer giving feedback) that you need to change something. Conveniently, Github tracks your branch so any change to it will also update the commits in your pull request.

For example, you make some new change to your branch, add and commit them:

git commit -am "this is an additional commit"

Then just push it to your branch:

git push

(Note: this assumes your local branch is set up to track your Github branch)

However, doing it like this is only recommended if the new commit actually adds something new to the branch, where it is logical to have it as a separate commit. If it is a bug fix for a previous commit in the same pull request, there is no need for us to see it in the master branch of pioneer once it is merged. Thus the following two subsections describe how to fix the commit log / history.

=== Update / change last commit ===

The first case is the simplest: if you just want to change the last commit in your branch, because you realized some file was missing, or needed an edit.

Make your change, then run "git add" on the changed files. Now update the last commit by:

git add <changed_file>
git commit --amend

And push to your Github, but since the hash id of the last commit has changed, you need to force it

git push -f

Done.

Note this also lets you reword the commit message.

=== Update / change commit in middle of the branch of the pull request ===

The second case covers if you need to edit commits further back in the commit history, or change order of commits or any other change.

The example case we use here has a git log looking like so:

git log --oneline
dd34lqe added final feature D
cc5369b added third feature C
bb1ed97 added second feature B
a528f11 added initial feature A

Now you want to fix a bug in your second commit for feature "B". Make your changes in your local branch, add them and commit. Your structure will now look like:

git log --oneline
98a9832 my bugfix for feature B
dd34lqe added final feature D
cc5369b added third feature C
bb1ed97 added second feature B
a528f11 added initial feature A

The bug fix commit is redundant to see in the git log once in master, so we want to merge the bug fix commit with "bb1ed97 my second feature B" commit, so that ''no one will ever know there was a bug in the first place''! You do this by "rebasing" your branch.

git rebase -i a528f11

This opens the rebase dialogue in your default editor for git (usually vim, emacs, or nano). It will show you the git history for all commits after (i.e. excluding) the commit a528f11 ("added initial feature A").

You will see in the editor something like this (don't be confused by the reverse order compared to git log command):

pick bb1ed97 added second feature B
pick cc5369b added third feature C
pick dd34lqe added final feature D
pick 98a9832 my bugfix for feature B

# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out

Now just move the last line to be just below the commit we want it to fix, and mark it as a "fixup", which will merge it into the commit above it, and use its commit message:

pick bb1ed97 added second feature B
fixup 98a9832 my bugfix for feature B
pick cc5369b added third feature C
pick dd34lqe added final feature D

Save, and quit, and hopefully git will report that the rebase was successful, and your git history will now be clean, but the commit hash (and code) for the "B feature" has changed, thus we need to force push the change to Github.

git log --oneline
dd34lqe added final feature D
cc5369b added third feature C
qq9860d added second feature B
a528f11 added initial feature A

git push -f

(again assuming your local branch is tracking the Github repo)

== Getting other developer's branches ==

If you want to get a copy of a branch from another developer, be that to test it, or to <code>cherry-pick</code> (covered elsewhere) commits into your own branch.

First make a branch from your master, and jump into it. It can be named whatever.

git checkout -b <branch-name> master

Now pull the code in from the developer's branch named <code><dev-branch></code>

git pull https://github.com/<developer-user-name>/pioneer.git <dev-branch>

If it's a developer you will often want to pull code from you can add him/her to your remote, just like you did with your own github <code>origin</code> and Pioneer's <code>upstream</code>.

git remote -v

add a new one, named <code><remote></code>.

git remote add <remote> <url>
git remote update
git checkout -b <branch-name> --track <remote>/<remote-branch-name>

== Keeping things tidy ==

If branch is merged into master then it can safely be deleted

git branch -d <branch-name>

If branch is not in master, then a force remove can be made

git branch -D <branch-name>

git push origin :<branch-name>

git clean -n

git clean -f

== Cherry picking ==

If wanting a commit from someone else, e.g. to add to your own branch, you can pull down their branch to your machine, then from the branch you want it to, just do:

git cherry-pick <commit-hash>

To actually do the "pulling down" of their branch to your machine:
<pre>git remote add dev-username git://path/to/dev-username/repo.git
git fetch dev-username</pre>

You might also be inetersted in following future changes in dev-username's branch:
<pre>git checkout --track dev-username/foo</pre>

Also, another useful tool, for those graphically inclined is:

gitk

'''Warning''': cherry picking, although sometimes useful, can cause problems for other developers if you use them on commits that have already been published to github. Be careful and give sufficient warnings if you find you needing to use them in that situation.

== Pushing to upstream Pioneer master ==

So you have working knowledge of git, and have been deemed not (too) crazy to be given commit access to the pioneer source? Welcome! As this means you can merge your own -- and others -- code into pioneer master, there are a few things you might want to know.

=== Guidelines for merge etiquette ===

The power to merge code on to a common code base requires mutual respect among the developers, and [https://en.wikipedia.org/wiki/Fingerspitzengefühl fingerspitzengefühl] based on the knowledge they have of each other, such as what their typical response time is, and where their area of expertise, and (code) interest/disinterests lies. If these principles were put into writing they might look something like the following:

*You still need to open pull requests (PR), and hold them open long enough for other developers to have a fair chance to have time to voice their opinion, and possibly/occasionally review it. Don't count on the latter though, you're responsible for what you break, and you are now expected to review your own code.

*An instant merge of a PR can be done from time to time when the change is trivial, and obviously "good", and/or working on code that is "your private realm" of the pioneer source, and/or when you or other person needs a feature in master as soon as possible, for the next build.

*Also, you may push a commit directly to master, with no PR, if the change is ''very'' trivial one-liner, for instance fixing a very silly error in just merged code.

*You may ''not'' ever do a forced push to pioneer master.

=== How to merge a PR the proper/pedantic way ===

For those with push access to https://github.com/pioneerspacesim/pioneer this is one way to push code to master. First make sure you have a resonable setup:

git remote -v
origin https://github.com/myusername/pioneer.git (fetch)
origin https://github.com/myusername/pioneer.git (push)
upstream https://github.com/pioneerspacesim/pioneer.git (fetch)
upstream https://github.com/pioneerspacesim/pioneer.git (push)

Also, it might be a god idea to clean your master branch, so you know it is identical to pioneer upstream, but do be warned, this will wipe your master branch, thus if you have commits that are not in their own branches, they will be lost (but retrievable through git reflog):

git checkout master
git reset --hard upstream/master

(For future merges, a simple git pull will suffice, if you've kept your master branch clean)

Now get the branch from the contributor to your computer, by creating an aptly named branch, and then pulling the code from the contributor to this branch.

git checkout -b name_of_branch_to_create
git pull https://github.com/contributor_username/pioneer.git name_of_branch_user_has

Now switch to your master, and merge it in, here we asume the branch you created was called "feature_branch"

git checkout master
git merge --no-commit --no-ff feature_branch

Document changes to Changelog.txt, then add it, so from the pioneer root folder, the path to Changelog wold just be:

git add Changelog.txt
git commit

This has now included the Changelog edit into the merge commit. Now do a dry run:

git push upstream master --dry-run

Check that the right commits will be pushed with

git log

And let us do it for real this time:

git push upstream master

Please note: NEVER do a force push to pioneer master!

== Advanced ==

Collecting some advanced tricks for developers

=== Push commit to someones PR ===

If you have push access to pioneer repo, then you also have push access to other contributor's pull requests.

Get the user's PR into a branch as usual:

git checkout -b some_user-feature_branch master
git pull https://github.com/some_user/pioneer.git feature_branch

make your changes, now push:

git push https://github.com/some_user/pioneer.git some_user-feature_branch:feature_branch

=== PR trick ===

For developers, or anyone interested, this trick will pull down all the pull requests from github, so you can easily switch to pull request, say, #1234 by doing

git checkout refs/pull/upstream/1234

=== Be a git pedantic? ===
Writing good [https://github.com/RomuloOliveira/commit-messages-guide commit messages], and being pedantic has its values.

== Links and resources ==
* [https://github.com/k88hudson/git-flight-rules git-flight-rules] Lots of examples, and links to further resources
* [https://ohshitgit.com/ Oh shit, git!] Fixing common mistakes in git
* [https://git-rebase.io/ git rebase in depth] Good guide on how to clean up/fix your git commit history

Pioneer Wiki

2020-05-11T02:08:54Z

Sturnclaw: /* Development */

Pioneer is a space adventure game set in the Milkyway galaxy at the turn of the 33rd century. The game is open-ended, and you are free to explore the millions of star systems in the game. You can land on planets, slingshot past gas giants, and burn yourself to a crisp flying between binary star systems.

If you are new to pioneer you may want to know [[How_to_start|how to start]].

*[http://pioneerspacesim.net/download Download Pioneer] for Windows, Linux and Mac OSX

Please make this wiki nice. Add stuff about mods, dev, whatever. Be awesome! [[Getting_started|How to get started]].

----

{| width="100%"
|-
| style="background:#bbffbb; border:2px solid #99ee99; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Community ===

*[http://pioneerspacesim.net/ Pioneer Space Sim Homepage]
*[https://github.com/pioneerspacesim/pioneer/ Main Github repository]
*[http://spacesimcentral.com/community/pioneer/ Community forum]
*[http://pioneerspacesim.net/forum Developer forum]
*[https://reddit.com/r/pioneerspacesim Pioneer Space Sim on Reddit]
*[https://pioneerspacesim.itch.io/pioneer Pioneer Space Sim on itch]
*[http://webchat.freenode.net/?channels=#pioneer Pioneer Space Sim on IRC] (where devs hang out)
*[http://twitter.com/pioneerspacesim @pioneerspacesim] on Twitter
*[https://discord.gg/RQQe3A7 discord]

----

*[[Manual|Basic Manual]]
*[[Flight_UI|Flight UI]]
*[[Keyboard_and_mouse_controls|Keyboard and mouse controls]]
*[[Tutorials|Tutorials]] (Outdated and WIP)
*[[Mission_Types_and_BBS|Mission Types and BBS]]
*[[Settings_Menu|Settings Menu]]
*[[FAQ|FAQ]]
*[[Media_Coverage|Media Coverage]]

| style="background:#fff9b1; border:2px solid #f0fe66; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |

=== The Pioneer Universe ===

*[[Pioneer_Universe|Pioneer Universe]]
*[[:Category:Ships| Ships]] (work in progress)
*[[:Category:Manufacturers| Manufacturers]] (work in progress)
*[[Places_of_interest|Places of interest]]
*[[Ship_Equipment|Ship Equipment]] (work in progress)

|}

 

{| width="100%"
|-
| style="background:#f0f0ff; border:2px solid #c6c9ff; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |

=== Content Creation ===

*[[Mods|Mods]]
*[[Scripting_and_Mission_Creation|Scripting and Mission Creation]]
*[[Custom_Systems|Custom Systems]]
*[[Design_and_Concept_art|Design and Concept art]]
*[[Modeling,_Texturing,_Graphics_Design|Modeling, Texturing, Graphics Design]]
*[[Music_and_Sound|Music and Sound]]
*[[Translations|Translations]]
*[[Licensing|Licensing]]

| style="background:#fff3e3; border:2px solid #ffc9c9; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Development ===

*[[Design_Scope|Game Scope]]
*[[How_you_can_contribute|How you can contribute]]
*[[Getting_Started_with_Development|Getting Started with Development]]
**[[How_to_communicate|How to communicate]]
**[[Using_git_and_GitHub|Using git and GitHub]]
**[[Coding Conventions]]
**[[Development_team|Development team]]
**[[Engine_Overview|Engine internals overview]]
*[[Development_Model|Development Model]]
*[[Design_Workflow|Design and Project Management Workflow]]
*[https://github.com/pioneerspacesim/pioneer/issues Issue tracker]
*[[Roadmap|Roadmap]]

|}

Pioneer is brought to you by a flock of [https://github.com/pioneerspacesim/pioneer/blob/master/AUTHORS.txt opensource beardy-weirdies], and is [http://www.gnu.org/licenses/gpl.html Free Software]

'''__NOTOC__'''

Coding Conventions

2020-05-11T02:08:05Z

Sturnclaw:

This page describes some of the code style used in Pioneer. As of 2019, we rely on clang to do our code-formatting checks for us. This means a Pull Request (PR) with incorrectly formatted code will fail the automated test. Please read [[Coding Conventions|Code Formatting]] for how to avoid this, and how to have our clang-format.sh script check your code before committing.

= General Concerns =

== Licensing ==

Engine and Lua code is licensed under [http://www.gnu.org/licenses/gpl.html GPL v3].

Assets (including Lua-based data files like custom systems) are licensed under [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3.0].

When submitting a file to the Pioneer repository, be sure to include these two lines at the top of each file (suitably commented):

Copyright © 2008-2020 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of the GPL v3. See licenses/GPL-3.txt

Copyright © 2008-2020 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of CC-BY-SA 3.0. See licenses/CC-BY-SA-3.0.txt

== Tabs & spacing ==

These standards are agreed upon for both C++ and Lua code - please make very sure to follow them!

* Hard tabs, 4-space aligned.
* Indent function arguments broken across multiple lines by one tab '''only'''. Do not add extra spaces to "line up" arguments with the opening parethesis.
* No trailing spaces, and don't indent blank lines
* Attention MS Windows users: lines end with Line Feed (LF), not Carriage Return (CR) or both (CRLF). If you can not fix it in your editor, git can do it for you [http://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#Formatting-and-Whitespace using the configuration option].

Some of our code doesn't follow this standard; if you're fixing up older indentation styles, please make sure to '''do that in its own commit''' so that other developers can review your changes more easily.

== Code Formatting ==

The Pioneer C++ codebase has an enforced common coding style, managed by running the <code>clang-format</code> tool. This is run by the Travis CI provider for all pull requests, and may also be run locally as a [https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks git hook]. If your Pull Request is displaying a red X or a message saying "All checks have failed", it is likely that your code has inadvertently broken the C++ code style that Pioneer uses.

=== Diagnosing Formatting Issues ===

If your Pull Request is in violation of Pioneer's code formatting rules, you can look at the Travis log to find out what parts of your code are specifically to blame. Click "Details" next to "The Travis CI build has failed" at the bottom of the Pull Request page, and select the "Static Checks" job from the resulting page. In the log below, the differences between your code and the correctly formatted code will be listed in [https://linux.die.net/man/1/diff diff(1)] format.

=== Installing a Git Hook ===

Looking at the Travis log to find out what changed is fine and well, but what you really should be doing is using a git hook to validate your code ''before'' you commit your changes. This process is very simple if you are developing on a Mac or Linux system - simply copy the pre-provided git hook into your local repository's <code>hooks/</code> directory. A pre-commit hook is not currently available for Windows systems. If you know how to reliably set one up, you are more than welcome to author it and submit it as a Pull Request.

<pre>
$ cp scripts/clang-format.sh .git/hooks/pre-commit-hook
</pre>

Once you have installed the hook, simply run <code>git commit</code> as normal. If your code doesn't comply with the C++ style rules, it will abort the commit and print the difference between your code and the properly formatted code to the console. If it succeeds, it will open an editor as normal.

If, for some reason, you wish to bypass the validation hook, simply run <code>git commit --no-verify</code>.

=== Applying The Format Changes ===

Once you know which files are improperly formatted, and what changes need to be made to fix them, you have two options. The first option is to manually apply the required changes to your code, and submit them as a new commit. Alternatively, you can use the automatic formatting tool. The interface is simple, presenting you with the list of changes made by clang-format and asking whether you would like to apply them. The invocation is simple as well:

<pre>
$ ./autoformat
</pre>

This will overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, as clang-format has some issues with detecting file types and may occasionally eat your work. Please read the diff and determine which changes will be made. If your version of clang-format is bugged and suggesting destructive changes, manually apply the correct changes and run `git-commit --no-verify` to bypass clang-format entirely.

= C++ Code Formatting Guide =

This section documents syntax and style guidelines that should be followed across the codebase.

Names should be concise and clear. They should easily communicate the purpose of object they represent. Names should not have type or qualifier information embedded in the name (the so-called [http://en.wikipedia.org/wiki/Hungarian_notation Systems Hungarian] notation). If a name isn't clear, it will cause confusion further down the line when someone else is editing your code.

If a function or variable refers to a quantity (e.g. atmospheric pressure, distance, etc.), please make sure it is well documented, including any assumptions it makes about the value and unit of the quantity. Unknowingly multiplying a value in Parsecs by a value in millimeters can take a while to track down, and it's very frustrating to everyone who has to debug it.

There are a few abbreviated names that are commonly used throughout the codebase, eg <code>Renderer *r</code>, <code>lua_State *l</code>, etc. Try to prefer them where appropriate.

== Classes ==

Class names should be written in PascalCase like so:

class MyClass {};

Structures intended to be used as an "integral type" like <code>vector3</code> should be written in lower case:

struct vector3 {};

Class-private or protected member variables should be prefixed with <tt>m_</tt>, using camelCase:

<pre>
class MyClass {
protected:
int m_someValue;
std::string m_anotherValue;
};
</pre>

Note that public member variables, especially in structures like <code>vector3</code>, do not follow the above conventions and are written without prefix.

Static member variables should be prefixed with <tt>s_</tt>, using camelCase:

<pre>
class MyClass {
protected:
static int s_classScopeVariable;
};
</pre>

All class functions (except those intentionally meant to follow the C++ STL's naming convention) should be written in PascalCase:

<pre>
class MyClass {
public:
void MyFunction() {}
};
</pre>

This includes static functions; they use the same naming convention as member functions, but their intended use should be well documented.

== Global variables ==

Global variables must be prefixed with <tt>g_</tt>, and use camelCase:

int g_screenWidth;

Please remember that raw global variables in C++ are considered bad practice; if you're writing code that uses them, you may want to rethink how you're accomplishing your goal.

Variables with static file scope should be prefixed with <tt>s_</tt>, and similarly use camelCase:

// ...
static int s_fileScopeVariable;

== Comments ==

Generally, use the style of the file you're working on. But the below is the general principle for commenting code.

* Use C++ comments rather than C comment blocks, unless you're writing multiple-paragraph comments.
* Many people work on the code, so please describe whenever function- and variable names are not enough.
* Especially comment when you think you're writing clever code
* That goes double for anything using the Lua stack manipulation functions - trailing comments showing the stack state are ''not'' overkill!

For documenting C++ functions one can use three slashes (<code>///</code>) or the Javadoc style (<code>/** ... */</code>) and it will be picked up by [http://doxygen.nl/manual/docblocks.html Doxygen]:

///
/// Function to be used only if user is willing to accept the return type
/// Do not use if prone to depression.
///
void meaningOfLife()

/**
* \brief Function documented by a Javadoc-style comment
*
* This is a fun function!
*/
void Explode()

Leading asterisks in Javadoc-style comments are not required - if the comment starts with exactly two asterisks, Doxygen will pick it up.

When not writing Doxygen documentation comments, please use regular C++ style (<code>//</code>) comments.

// Regular comment in code for other programmers mucking about (example code from Quake3):

float InvSqrt (float x){
float xhalf = 0.5f*x;
int i = *(int*)&x;

// I really should have documented this
i = 0x5f3759df - (i>>1);

x = *(float*)&i;
x = x*(1.5f - xhalf*x*x);
return x;
}

Please make sure your comments are informative - they should provide information to future programmers that might not be obvious from reading the variable names:

// entered if we are flying
// (BAD!)
if(isFlying)
{
// If the atmospheric pressure exceeds the crush point of the hull (as expressed in arbitrary units)
// we, naturally, explode.
// (GOOD!)
if (GetAtmoPressure() > 5103.0 / m_maxBar) {
Explode();

If something is broken, or temporarily disabled, or needs re-thinking, make use of TODO markers at the beginning of your code. Most modern IDEs have plugins to display these comments neatly so future programmers can easily see work that needs to be done:

// FIXME(sturnclaw): add a better interface for retrieving a global time source
// TODO: re-initialise the turntable style view position from the current mouselook view
// HACK: attempt to recognise `foo_3.png' style names

Signing your comments (e.g. <code>FIXME(sturnclaw):</code>) isn't required, but is good practice if the TODO is about something you intend to work on further.

=== Lua API Documentation ===

For [https://pioneerspacesim.net/codedoc/ LuaAPI] documentation we use NaturalDocs v2; this documentation is pulled from C++ and lua source files. This documentation follows the NaturalDocs [https://www.naturaldocs.org/getting_started/documenting_your_code/ conventions].

The syntax is very simple and easy to work with. Leading asterisks on each line of documentation are optional; NaturalDocs will read regular block comments as well.

/*
* Method: Fly
*
* Fly high in the sky
*
* > ship:fly()
*
* Availability:
*
* 2015
*
* Status:
*
* experimental
*/
static int l_fly_high_in_the_sky(lua_State *l)
{
// code goes here
return 0;
}

== Constants and Macros ==

When defining file or class-scope constants, never use <code>#define</code> - prefer C++ static constants or better yet <code>constexpr</code> where possible.

static const double M_PI = 3.14159;
static constexpr double M_PI = 3.14159;

The use of macros should be kept to a minimum - using a macro in a local scope to reduce boilerplate is acceptable, but macros in headers should only be used when there is no other alternative. Remember to always <code>#undef</code> local macros as soon as they are done being used to prevent accidental name pollution and other issues.

=== Include guards ===

Pioneer is (slowly and unofficially) moving away from include guards and using <code>#pragma once</code> as it's easier, less accident-prone (name collisions anyone?), and well supported by all modern compilers. However, we're not rejecting code using include guards instead.

Header include guards should be named for the filename of the header, capitalised, with slashes converted to underscores:

// Ship.h
#ifndef SHIP_H

// WorldView.h
#ifndef WORLDVIEW_H

// graphics/Renderer.h
#ifndef GRAPHICS_RENDERER_H

== Enum types ==

Prefer using C++ style <tt>enum class</tt> declarations when writing new code. They're slightly more difficult to serialize (although only to the extent of requiring a <code>static_cast</code>), but they encourage much more correct code.

No matter which style of enum you're using, try to follow these guidelines:
* Avoid assigning explicit integer values.
* Also avoid values that aren't actually valid for whatever the enum is (though *_MAX to mark the last valid value is usually acceptable).
* If these don't work, chances are what you're trying to do would be better served by multiple enums or even a whole class.

=== C-style Enums ===

Enums are effectively global constants, so should be in full caps. They're prefixed with the name of the enum.

enum Thing {
THING_FOO,
THING_BAR,
THING_BAZ,

THING_MAX
};

If you're writing new code and can't use C++-style enum classes, consider using C-style enums scoped in a struct to avoid polluting the global namespace.

<pre>
struct Thing {
enum Thing {
Foo,
Bar,
Baz,

THING_MAX
};
};
</pre>

=== C++-style Enum Class ===

C++ style enums are closer to classes, and thus they (and their members) should use PascalCase.

<pre>
enum class Thing : uint8_t {
Foo,
Bar,
Baz
};
</pre>

= Lua Code Formatting Guide =

This section is TODO...

Coding Conventions

2020-05-11T02:02:35Z

Sturnclaw:

This page describes some of the code style used in Pioneer. As of 2019, we rely on clang to do our code-formatting checks for us. This means a Pull Request (PR) with incorrectly formatted code will fail the automated test. Please read [[Coding Conventions|Code Formatting]] for how to avoid this, and how to have our clang-format.sh script check your code before committing.

== Licensing ==

Engine and Lua code is licensed under [http://www.gnu.org/licenses/gpl.html GPL v3].

Assets (including Lua-based data files like custom systems) are licensed under [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3.0].

When submitting a file to the Pioneer repository, be sure to include these two lines at the top of each file (suitably commented):

Copyright © 2008-2020 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of the GPL v3. See licenses/GPL-3.txt

Copyright © 2008-2020 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of CC-BY-SA 3.0. See licenses/CC-BY-SA-3.0.txt

== Tabs & spacing ==

These standards are agreed upon for both C++ and Lua code - please make very sure to follow them!

* Hard tabs, 4-space aligned.
* Indent function arguments broken across multiple lines by one tab '''only'''. Do not add extra spaces to "line up" arguments with the opening parethesis.
* No trailing spaces, and don't indent blank lines
* Attention MS Windows users: lines end with Line Feed (LF), not Carriage Return (CR) or both (CRLF). If you can not fix it in your editor, git can do it for you [http://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#Formatting-and-Whitespace using the configuration option].

Some of our code doesn't follow this standard; if you're fixing up older indentation styles, please make sure to '''do that in its own commit''' so that other developers can review your changes more easily.

== Code Formatting ==

The Pioneer C++ codebase has an enforced common coding style, managed by running the <code>clang-format</code> tool. This is run by the Travis CI provider for all pull requests, and may also be run locally as a [https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks git hook]. If your Pull Request is displaying a red X or a message saying "All checks have failed", it is likely that your code has inadvertently broken the C++ code style that Pioneer uses.

=== Diagnosing Formatting Issues ===

If your Pull Request is in violation of Pioneer's code formatting rules, you can look at the Travis log to find out what parts of your code are specifically to blame. Click "Details" next to "The Travis CI build has failed" at the bottom of the Pull Request page, and select the "Static Checks" job from the resulting page. In the log below, the differences between your code and the correctly formatted code will be listed in [https://linux.die.net/man/1/diff diff(1)] format.

=== Installing a Git Hook ===

Looking at the Travis log to find out what changed is fine and well, but what you really should be doing is using a git hook to validate your code ''before'' you commit your changes. This process is very simple if you are developing on a Mac or Linux system - simply copy the pre-provided git hook into your local repository's <code>hooks/</code> directory. A pre-commit hook is not currently available for Windows systems. If you know how to reliably set one up, you are more than welcome to author it and submit it as a Pull Request.

<pre>
$ cp scripts/clang-format.sh .git/hooks/pre-commit-hook
</pre>

Once you have installed the hook, simply run <code>git commit</code> as normal. If your code doesn't comply with the C++ style rules, it will abort the commit and print the difference between your code and the properly formatted code to the console. If it succeeds, it will open an editor as normal.

If, for some reason, you wish to bypass the validation hook, simply run <code>git commit --no-verify</code>.

=== Applying The Format Changes ===

Once you know which files are improperly formatted, and what changes need to be made to fix them, you have two options. The first option is to manually apply the required changes to your code, and submit them as a new commit. Alternatively, you can use the automatic formatting tool. The interface is simple, presenting you with the list of changes made by clang-format and asking whether you would like to apply them. The invocation is simple as well:

<pre>
$ ./autoformat
</pre>

This will overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, as clang-format has some issues with detecting file types and may occasionally eat your work. Please read the diff and determine which changes will be made. If your version of clang-format is bugged and suggesting destructive changes, manually apply the correct changes and run `git-commit --no-verify` to bypass clang-format entirely.

== C++ Code Formatting Guide ==

This section documents syntax and style guidelines that should be followed across the codebase.

Names should be concise and clear. They should easily communicate the purpose of object they represent. Names should not have type or qualifier information embedded in the name (the so-called [http://en.wikipedia.org/wiki/Hungarian_notation Systems Hungarian] notation). If a name isn't clear, it will cause confusion further down the line when someone else is editing your code.

If a function or variable refers to a quantity (e.g. atmospheric pressure, distance, etc.), please make sure it is well documented, including any assumptions it makes about the value and unit of the quantity. Unknowingly multiplying a value in Parsecs by a value in millimeters can take a while to track down, and it's very frustrating to everyone who has to debug it.

There are a few abbreviated names that are commonly used throughout the codebase, eg <code>Renderer *r</code>, <code>lua_State *l</code>, etc. Try to prefer them where appropriate.

=== Classes ===

Class names should be written in PascalCase like so:

class MyClass {};

Structures intended to be used as an "integral type" like <code>vector3</code> should be written in lower case:

struct vector3 {};

Class-private or protected member variables should be prefixed with <tt>m_</tt>, using camelCase:

<pre>
class MyClass {
protected:
int m_someValue;
std::string m_anotherValue;
};
</pre>

Note that public member variables, especially in structures like <code>vector3</code>, do not follow the above conventions and are written without prefix.

Static member variables should be prefixed with <tt>s_</tt>, using camelCase:

<pre>
class MyClass {
protected:
static int s_classScopeVariable;
};
</pre>

All class functions (except those intentionally meant to follow the C++ STL's naming convention) should be written in PascalCase:

<pre>
class MyClass {
public:
void MyFunction() {}
};
</pre>

This includes static functions; they use the same naming convention as member functions, but their intended use should be well documented.

=== Global variables ===

Global variables must be prefixed with <tt>g_</tt>, and use camelCase:

int g_screenWidth;

Please remember that raw global variables in C++ are considered bad practice; if you're writing code that uses them, you may want to rethink how you're accomplishing your goal.

Variables with static file scope should be prefixed with <tt>s_</tt>, and similarly use camelCase:

// ...
static int s_fileScopeVariable;

== Comments ==

Generally, use the style of the file you're working on. But the below is the general principle for commenting code.

* Use C++ comments rather than C comment blocks, unless you're writing multiple-paragraph comments.
* Many people work on the code, so please describe whenever function- and variable names are not enough.
* Especially comment when you think you're writing clever code
* That goes double for anything using the Lua stack manipulation functions - trailing comments showing the stack state are ''not'' overkill!

For documenting C++ functions one can use three slashes (<code>///</code>) or the Javadoc style (<code>/** ... */</code>) and it will be picked up by [http://doxygen.nl/manual/docblocks.html Doxygen]:

///
/// Function to be used only if user is willing to accept the return type
/// Do not use if prone to depression.
///
void meaningOfLife()

/**
* \brief Function documented by a Javadoc-style comment
*
* This is a fun function!
*/
void Explode()

Leading asterisks in Javadoc-style comments are not required - if the comment starts with exactly two asterisks, Doxygen will pick it up.

When not writing Doxygen documentation comments, please use regular C++ style (<code>//</code>) comments.

// Regular comment in code for other programmers mucking about (example code from Quake3):

float InvSqrt (float x){
float xhalf = 0.5f*x;
int i = *(int*)&x;

// I really should have documented this
i = 0x5f3759df - (i>>1);

x = *(float*)&i;
x = x*(1.5f - xhalf*x*x);
return x;
}

Please make sure your comments are informative - they should provide information to future programmers that might not be obvious from reading the variable names:

// entered if we are flying
// (BAD!)
if(isFlying)
{
// If the atmospheric pressure exceeds the crush point of the hull (as expressed in arbitrary units)
// we, naturally, explode.
// (GOOD!)
if (GetAtmoPressure() > 5103.0 / m_maxBar) {
Explode();

If something is broken, or temporarily disabled, or needs re-thinking, make use of TODO markers at the beginning of your code. Most modern IDEs have plugins to display these comments neatly so future programmers can easily see work that needs to be done:

// FIXME(sturnclaw): add a better interface for retrieving a global time source
// TODO: re-initialise the turntable style view position from the current mouselook view
// HACK: attempt to recognise `foo_3.png' style names

Signing your comments (e.g. <code>FIXME(sturnclaw):</code>) isn't required, but is good practice if the TODO is about something you intend to work on further.

=== Lua API Documentation ===

For [https://pioneerspacesim.net/codedoc/ LuaAPI] documentation we use NaturalDocs v2; this documentation is pulled from C++ and lua source files. This documentation follows the NaturalDocs [https://www.naturaldocs.org/getting_started/documenting_your_code/ conventions].

The syntax is very simple and easy to work with. Leading asterisks on each line of documentation are optional; NaturalDocs will read regular block comments as well.

/*
* Method: Fly
*
* Fly high in the sky
*
* > ship:fly()
*
* Availability:
*
* 2015
*
* Status:
*
* experimental
*/
static int l_fly_high_in_the_sky(lua_State *l)
{
// code goes here
return 0;
}

== Constants and Macros ==

When defining file or class-scope constants, never use <code>#define</code> - prefer C++ static constants or better yet <code>constexpr</code> where possible.

static const double M_PI = 3.14159;
static constexpr double M_PI = 3.14159;

The use of macros should be kept to a minimum - using a macro in a local scope to reduce boilerplate is acceptable, but macros in headers should only be used when there is no other alternative. Remember to always <code>#undef</code> local macros as soon as they are done being used to prevent accidental name pollution and other issues.

== Include guards ==

Pioneer is (slowly and unofficially) moving away from include guards and using <code>#pragma once</code> as it's easier, less accident-prone (name collisions anyone?), and well supported by all modern compilers. However, we're not rejecting code using include guards instead.

Header include guards should be named for the filename of the header, capitalised, with slashes converted to underscores:

// Ship.h
#ifndef SHIP_H

// WorldView.h
#ifndef WORLDVIEW_H

// graphics/Renderer.h
#ifndef GRAPHICS_RENDERER_H

== Enum types ==

Prefer using C++ style <tt>enum class</tt> declarations when writing new code. They're slightly more difficult to serialize (although only to the extent of requiring a <code>static_cast</code>), but they encourage much more correct code.

No matter which style of enum you're using, try to follow these guidelines:
* Avoid assigning explicit integer values.
* Also avoid values that aren't actually valid for whatever the enum is (though *_MAX to mark the last valid value is usually acceptable).
* If these don't work, chances are what you're trying to do would be better served by multiple enums or even a whole class.

=== C-style Enums ===

Enums are effectively global constants, so should be in full caps. They're prefixed with the name of the enum.

enum Thing {
THING_FOO,
THING_BAR,
THING_BAZ,

THING_MAX
};

If you're writing new code and can't use C++-style enum classes, consider using C-style enums scoped in a struct to avoid polluting the global namespace.

<pre>
struct Thing {
enum Thing {
Foo,
Bar,
Baz,

THING_MAX
};
};
</pre>

=== C++-style Enum Class ===

C++ style enums are closer to classes, and thus they (and their members) should use PascalCase.

<pre>
enum class Thing : uint8_t {
Foo,
Bar,
Baz
};
</pre>

Coding Conventions

2020-05-11T02:00:25Z

Sturnclaw:

This page describes some of the code style used in Pioneer. As of 2019, we rely on clang to do our code-formatting checks for us. This means a Pull Request (PR) with incorrectly formatted code will fail the automated test. Please read [[Coding Conventions|Code Formatting]] for how to avoid this, and how to have our clang-format.sh script check your code before committing.

== Licensing ==

Engine and Lua code is licensed under [http://www.gnu.org/licenses/gpl.html GPL v3].

Assets (including Lua-based data files like custom systems) are licensed under [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3.0].

When submitting a file to the Pioneer repository, be sure to include these two lines at the top of each file (suitably commented):

Copyright © 2008-2020 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of the GPL v3. See licenses/GPL-3.txt

Copyright © 2008-2020 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of CC-BY-SA 3.0. See licenses/CC-BY-SA-3.0.txt

== Tabs & spacing ==

These standards are agreed upon for both C++ and Lua code - please make very sure to follow them!

* Hard tabs, 4-space aligned.
* Indent function arguments broken across multiple lines by one tab '''only'''. Do not add extra spaces to "line up" arguments with the opening parethesis.
* No trailing spaces, and don't indent blank lines
* Attention MS Windows users: lines end with Line Feed (LF), not Carriage Return (CR) or both (CRLF). If you can not fix it in your editor, git can do it for you [http://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#Formatting-and-Whitespace using the configuration option].

Some of our code doesn't follow this standard; if you're fixing up older indentation styles, please make sure to '''do that in its own commit''' so that other developers can review your changes more easily.

== Code Formatting ==

The Pioneer C++ codebase has an enforced common coding style, managed by running the <code>clang-format</code> tool. This is run by the Travis CI provider for all pull requests, and may also be run locally as a [https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks git hook]. If your Pull Request is displaying a red X or a message saying "All checks have failed", it is likely that your code has inadvertently broken the C++ code style that Pioneer uses.

=== Diagnosing Formatting Issues ===

If your Pull Request is in violation of Pioneer's code formatting rules, you can look at the Travis log to find out what parts of your code are specifically to blame. Click "Details" next to "The Travis CI build has failed" at the bottom of the Pull Request page, and select the "Static Checks" job from the resulting page. In the log below, the differences between your code and the correctly formatted code will be listed in [https://linux.die.net/man/1/diff diff(1)] format.

=== Installing a Git Hook ===

Looking at the Travis log to find out what changed is fine and well, but what you really should be doing is using a git hook to validate your code ''before'' you commit your changes. This process is very simple if you are developing on a Mac or Linux system - simply copy the pre-provided git hook into your local repository's <code>hooks/</code> directory. A pre-commit hook is not currently available for Windows systems. If you know how to reliably set one up, you are more than welcome to author it and submit it as a Pull Request.

<pre>
$ cp scripts/clang-format.sh .git/hooks/pre-commit-hook
</pre>

Once you have installed the hook, simply run <code>git commit</code> as normal. If your code doesn't comply with the C++ style rules, it will abort the commit and print the difference between your code and the properly formatted code to the console. If it succeeds, it will open an editor as normal.

If, for some reason, you wish to bypass the validation hook, simply run <code>git commit --no-verify</code>.

=== Applying The Format Changes ===

Once you know which files are improperly formatted, and what changes need to be made to fix them, you have two options. The first option is to manually apply the required changes to your code, and submit them as a new commit. Alternatively, you can use the automatic formatting tool. The interface is simple, presenting you with the list of changes made by clang-format and asking whether you would like to apply them. The invocation is simple as well:

<pre>
$ ./autoformat
</pre>

This will overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, as clang-format has some issues with detecting file types and may occasionally eat your work. Please read the diff and determine which changes will be made. If your version of clang-format is bugged and suggesting destructive changes, manually apply the correct changes and run `git-commit --no-verify` to bypass clang-format entirely.

== C++ Code Formatting Guide ==

This section documents syntax and style guidelines that should be followed across the codebase.

Names should be concise and clear. They should easily communicate the purpose of object they represent. Names should not have type or qualifier information embedded in the name (the so-called [http://en.wikipedia.org/wiki/Hungarian_notation Systems Hungarian] notation). If a name isn't clear, it will cause confusion further down the line when someone else is editing your code.

If a function or variable refers to a quantity (e.g. atmospheric pressure, distance, etc.), please make sure it is well documented, including any assumptions it makes about the value and unit of the quantity. Unknowingly multiplying a value in Parsecs by a value in millimeters can take a while to track down, and it's very frustrating to everyone who has to debug it.

There are a few abbreviated names that are commonly used throughout the codebase, eg <code>Renderer *r</code>, <code>lua_State *l</code>, etc. Try to prefer them where appropriate.

=== Classes ===

Class names should be written in PascalCase like so:

class MyClass {};

Structures intended to be used as an "integral type" like <code>vector3</code> should be written in lower case:

struct vector3 {};

Class-private or protected member variables should be prefixed with <tt>m_</tt>, using camelCase:

<pre>
class MyClass {
protected:
int m_someValue;
std::string m_anotherValue;
};
</pre>

Note that public member variables, especially in structures like <code>vector3</code>, do not follow the above conventions and are written without prefix.

Static member variables should be prefixed with <tt>s_</tt>, using camelCase:

<pre>
class MyClass {
protected:
static int s_classScopeVariable;
};
</pre>

All class functions (except those intentionally meant to follow the C++ STL's naming convention) should be written in PascalCase:

<pre>
class MyClass {
public:
void MyFunction() {}
};
</pre>

This includes static functions; they use the same naming convention as member functions, but their intended use should be well documented.

=== Global variables ===

Global variables must be prefixed with <tt>g_</tt>, and use camelCase:

int g_screenWidth;

Please remember that raw global variables in C++ are considered bad practice; if you're writing code that uses them, you may want to rethink how you're accomplishing your goal.

Variables with static file scope should be prefixed with <tt>s_</tt>, and similarly use camelCase:

// ...
static int s_fileScopeVariable;

== Comments ==

Generally, use the style of the file you're working on. But the below is the general principle for commenting code.

* Use C++ comments rather than C comment blocks, unless you're writing multiple-paragraph comments.
* Many people work on the code, so please describe whenever function- and variable names are not enough.
* Especially comment when you think you're writing clever code
* That goes double for anything using the Lua stack manipulation functions - trailing comments showing the stack state are ''not'' overkill!

For documenting C++ functions one can use three slashes (<code>///</code>) or the Javadoc style (<code>/** ... */</code>) and it will be picked up by [http://doxygen.nl/manual/docblocks.html Doxygen]:

///
/// Function to be used only if user is willing to accept the return type
/// Do not use if prone to depression.
///
void meaningOfLife()

/**
* \brief Function documented by a Javadoc-style comment
*
* This is a fun function!
*/
void Explode()

Leading asterisks in Javadoc-style comments are not required - if the comment starts with exactly two asterisks, Doxygen will pick it up.

When not writing Doxygen documentation comments, please use regular C++ style (<code>//</code>) comments.

// Regular comment in code for other programmers mucking about (example code from Quake3):

float InvSqrt (float x){
float xhalf = 0.5f*x;
int i = *(int*)&x;

// I really should have documented this
i = 0x5f3759df - (i>>1);

x = *(float*)&i;
x = x*(1.5f - xhalf*x*x);
return x;
}

Please make sure your comments are informative - they should provide information to future programmers that might not be obvious from reading the variable names:

// entered if we are flying
// (BAD!)
if(isFlying)
{
// If the atmospheric pressure exceeds the crush point of the hull (as expressed in arbitrary units)
// we, naturally, explode.
// (GOOD!)
if (GetAtmoPressure() > 5103.0 / m_maxBar) {
Explode();

If something is broken, or temporarily disabled, or needs re-thinking, make use of TODO markers at the beginning of your code. Most modern IDEs have plugins to display these comments neatly so future programmers can easily see work that needs to be done:

// FIXME(sturnclaw): add a better interface for retrieving a global time source
// TODO: re-initialise the turntable style view position from the current mouselook view
// HACK: attempt to recognise `foo_3.png' style names

Signing your comments (e.g. <code>FIXME(sturnclaw):</code>) isn't required, but is good practice if the TODO is about something you intend to work on further.

=== Lua API Documentation ===

For [https://pioneerspacesim.net/codedoc/ LuaAPI] documentation we use NaturalDocs v2; this documentation is pulled from C++ and lua source files. This documentation follows the NaturalDocs [https://www.naturaldocs.org/getting_started/documenting_your_code/ conventions].

The syntax is very simple and easy to work with. Leading asterisks on each line of documentation are optional; NaturalDocs will read regular block comments as well.

/*
* Method: Fly
*
* Fly high in the sky
*
* > ship:fly()
*
* Availability:
*
* 2015
*
* Status:
*
* experimental
*/
static int l_fly_high_in_the_sky(lua_State *l)
{
// code goes here
return 0;
}

== Constants and Macros ==

When defining file or class-scope constants, never use <code>#define</code> - prefer C++ static constants or better yet <code>constexpr</code> where possible.

static const double M_PI = 3.14159;
static constexpr double M_PI = 3.14159;

The use of macros should be kept to a minimum - using a macro in a local scope to reduce boilerplate is acceptable, but macros in headers should only be used when there is no other alternative. Remember to always <code>#undef</code> local macros as soon as they are done being used to prevent accidental name pollution and other issues.

== Include guards ==

Pioneer is (slowly and unofficially) moving away from include guards and using <code>#pragma once</code> as it's easier, less accident-prone (name collisions anyone?), and well supported by all modern compilers. However, we're not rejecting code using include guards instead.

Header include guards should be named for the filename of the header, capitalised, with slashes converted to underscores:

// Ship.h
#ifndef SHIP_H

// WorldView.h
#ifndef WORLDVIEW_H

// graphics/Renderer.h
#ifndef GRAPHICS_RENDERER_H

== Enum types ==

Prefer using C++ style <tt>enum class</tt> declarations when writing new code. They're slightly more difficult to serialize (although only to the extent of requiring a <code>static_cast</code>), but they encourage much more correct code.

No matter which style of enum you're using, try to follow these guidelines:
* Avoid assigning explicit integer values.
* Also avoid values that aren't actually valid for whatever the enum is (though *_MAX to mark the last valid value is usually acceptable).
* If these don't work, chances are what you're trying to do would be better served by multiple enums or even a whole class.

=== C-style Enums ===

Enums are effectively global constants, so should be in full caps. They're prefixed with the name of the enum.

enum Thing {
THING_FOO,
THING_BAR,
THING_BAZ,

THING_MAX
};

=== C++-style Enum Class ===

C++ style enums are closer to classes, and thus they (and their members) should use PascalCase.

<pre>
enum class Thing : uint8_t {
Foo,
Bar,
Baz
};
</pre>

Make sure your enumeration only contains valid values - if you need a <tt>_Max</tt> element, consider using C-style enums scoped in a struct to avoid polluting the global namespace.

<pre>
struct Thing {
enum Thing {
Foo,
Bar,
Baz,

THING_MAX
};
};
</pre>

Coding Conventions

2020-05-11T01:58:53Z

Sturnclaw: Unify coding style convention documentation.

This page describes some of the code style used in Pioneer. As of 2019, we rely on clang to do our code-formatting checks for us. This means a Pull Request (PR) with incorrectly formatted code will fail the automated test. Please read [[Coding Conventions|Code Formatting]] for how to avoid this, and how to have our clang-format.sh script check your code before committing.

== Licensing ==

Engine and Lua code is licensed under [http://www.gnu.org/licenses/gpl.html GPL v3].

Assets (including Lua-based data files like custom systems) are licensed under [http://creativecommons.org/licenses/by-sa/3.0/ CC-BY-SA 3.0].

When submitting a file to the Pioneer repository, be sure to include these two lines at the top of each file (suitably commented):

Copyright © 2008-2020 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of the GPL v3. See licenses/GPL-3.txt

Copyright © 2008-2020 Pioneer Developers. See AUTHORS.txt for details
Licensed under the terms of CC-BY-SA 3.0. See licenses/CC-BY-SA-3.0.txt

== Tabs & spacing ==

These standards are agreed upon for both C++ and Lua code - please make very sure to follow them!

* Hard tabs, 4-space aligned.
* Indent function arguments broken across multiple lines by one tab '''only'''. Do not add extra spaces to "line up" arguments with the opening parethesis.
* No trailing spaces, and don't indent blank lines
* Attention MS Windows users: lines end with Line Feed (LF), not Carriage Return (CR) or both (CRLF). If you can not fix it in your editor, git can do it for you [http://git-scm.com/book/en/v2/Customizing-Git-Git-Configuration#Formatting-and-Whitespace using the configuration option].

Some of our code doesn't follow this standard; if you're fixing up older indentation styles, please make sure to '''do that in its own commit''' so that other developers can review your changes more easily.

== Code Formatting ==

The Pioneer C++ codebase has an enforced common coding style, managed by running the <code>clang-format</code> tool. This is run by the Travis CI provider for all pull requests, and may also be run locally as a [https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks git hook]. If your Pull Request is displaying a red X or a message saying "All checks have failed", it is likely that your code has inadvertently broken the C++ code style that Pioneer uses.

=== Diagnosing Formatting Issues ===

If your Pull Request is in violation of Pioneer's code formatting rules, you can look at the Travis log to find out what parts of your code are specifically to blame. Click "Details" next to "The Travis CI build has failed" at the bottom of the Pull Request page, and select the "Static Checks" job from the resulting page. In the log below, the differences between your code and the correctly formatted code will be listed in [https://linux.die.net/man/1/diff diff(1)] format.

=== Installing a Git Hook ===

Looking at the Travis log to find out what changed is fine and well, but what you really should be doing is using a git hook to validate your code ''before'' you commit your changes. This process is very simple if you are developing on a Mac or Linux system - simply copy the pre-provided git hook into your local repository's <code>hooks/</code> directory. A pre-commit hook is not currently available for Windows systems. If you know how to reliably set one up, you are more than welcome to author it and submit it as a Pull Request.

<pre>
$ cp scripts/clang-format.sh .git/hooks/pre-commit-hook
</pre>

Once you have installed the hook, simply run <code>git commit</code> as normal. If your code doesn't comply with the C++ style rules, it will abort the commit and print the difference between your code and the properly formatted code to the console. If it succeeds, it will open an editor as normal.

If, for some reason, you wish to bypass the validation hook, simply run <code>git commit --no-verify</code>.

=== Applying The Format Changes ===

Once you know which files are improperly formatted, and what changes need to be made to fix them, you have two options. The first option is to manually apply the required changes to your code, and submit them as a new commit. Alternatively, you can use the automatic formatting tool. The interface is simple, presenting you with the list of changes made by clang-format and asking whether you would like to apply them. The invocation is simple as well:

<pre>
$ ./autoformat
</pre>

This will overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, as clang-format has some issues with detecting file types and may occasionally eat your work. Please read the diff and determine which changes will be made. If your version of clang-format is bugged and suggesting destructive changes, manually apply the correct changes and run `git-commit --no-verify` to bypass clang-format entirely.

== C++ Code Formatting Guide ==

This section documents syntax and style guidelines that should be followed across the codebase.

Names should be concise and clear. They should easily communicate the purpose of object they represent. Names should not have type or qualifier information embedded in the name (the so-called [http://en.wikipedia.org/wiki/Hungarian_notation Systems Hungarian] notation). If a name isn't clear, it will cause confusion further down the line when someone else is editing your code.

If a function or variable refers to a quantity (e.g. atmospheric pressure, distance, etc.), please make sure it is well documented, including any assumptions it makes about the value and unit of the quantity. Unknowingly multiplying a value in Parsecs by a value in millimeters can take a while to track down, and it's very frustrating to everyone who has to debug it.

There are a few abbreviated names that are commonly used throughout the codebase, eg <code>Renderer *r</code>, <code>lua_State *l</code>, etc. Try to prefer them where appropriate.

=== Classes ===

Class names should be written in PascalCase like so:

class MyClass {};

Structures intended to be used as an "integral type" like <code>vector3</code> should be written in lower case:

struct vector3 {};

Class-private or protected member variables should be prefixed with <tt>m_</tt>, using camelCase:

<pre>
class MyClass {
protected:
int m_someValue;
std::string m_anotherValue;
};
</pre>

Note that public member variables, especially in structures like <code>vector3</code>, do not follow the above conventions and are written without prefix.

Static member variables should be prefixed with <tt>s_</tt>, using camelCase:

<pre>
class MyClass {
protected:
static int s_classScopeVariable;
};
</pre>

All class functions (except those intentionally meant to follow the C++ STL's naming convention) should be written in PascalCase:

<pre>
class MyClass {
public:
void MyFunction() {}
};
</pre>

This includes static functions; they use the same naming convention as member functions, but their intended use should be well documented.

=== Global variables ===

Global variables must be prefixed with <tt>g_</tt>, and use camelCase:

int g_screenWidth;

Please remember that raw global variables in C++ are considered bad practice; if you're writing code that uses them, you may want to rethink how you're accomplishing your goal.

Variables with static file scope should be prefixed with <tt>s_</tt>, and similarly use camelCase:

// ...
static int s_fileScopeVariable;

== Comments ==

Generally, use the style of the file you're working on. But the below is the general principle for commenting code.

* Use C++ comments rather than C comment blocks, unless you're writing multiple-paragraph comments.
* Many people work on the code, so please describe whenever function- and variable names are not enough.
* Especially comment when you think you're writing clever code
* That goes double for anything using the Lua stack manipulation functions - trailing comments showing the stack state are ''not'' overkill!

For documenting C++ functions one can use three slashes (<code>///</code>) or the Javadoc style (<code>/** ... */</code>) and it will be picked up by [http://doxygen.nl/manual/docblocks.html Doxygen]:

///
/// Function to be used only if user is willing to accept the return type
/// Do not use if prone to depression.
///
void meaningOfLife()

/**
* \brief Function documented by a Javadoc-style comment
*
* This is a fun function!
*/
void Explode()

Leading asterisks in Javadoc-style comments are not required - if the comment starts with exactly two asterisks, Doxygen will pick it up.

When not writing Doxygen documentation comments, please use regular C++ style (<code>//</code>) comments.

// Regular comment in code for other programmers mucking about (example code from Quake3):

float InvSqrt (float x){
float xhalf = 0.5f*x;
int i = *(int*)&x;

// I really should have documented this
i = 0x5f3759df - (i>>1);

x = *(float*)&i;
x = x*(1.5f - xhalf*x*x);
return x;
}

Please make sure your comments are informative - they should provide information to future programmers that might not be obvious from reading the variable names:

// entered if we are flying
// (BAD!)
if(isFlying)
{
// If the atmospheric pressure exceeds the crush point of the hull (as expressed in arbitrary units)
// we, naturally, explode.
// (GOOD!)
if (GetAtmoPressure() > 5103.0 / m_maxBar) {
Explode();

If something is broken, or temporarily disabled, or needs re-thinking, make use of TODO markers at the beginning of your code. Most modern IDEs have plugins to display these comments neatly so future programmers can easily see work that needs to be done:

// FIXME(sturnclaw): add a better interface for retrieving a global time source
// TODO: re-initialise the turntable style view position from the current mouselook view
// HACK: attempt to recognise `foo_3.png' style names

Signing your comments (e.g. <code>FIXME(sturnclaw):</code>) isn't required, but is good practice if the TODO is about something you intend to work on further.

=== Lua API Documentation ===

For [https://pioneerspacesim.net/codedoc/ LuaAPI] documentation we use NaturalDocs v2; this documentation is pulled from C++ and lua source files. This documentation follows the NaturalDocs [https://www.naturaldocs.org/getting_started/documenting_your_code/ conventions].

The syntax is very simple and easy to work with. Leading asterisks on each line of documentation are optional; NaturalDocs will read regular block comments as well.

/*
* Method: Fly
*
* Fly high in the sky
*
* > ship:fly()
*
* Availability:
*
* 2015
*
* Status:
*
* experimental
*/
static int l_fly_high_in_the_sky(lua_State *l)
{
// code goes here
return 0;
}

== Constants and Macros ==

When defining file or class-scope constants, never use <code>#define</code> - prefer C++ static constants or better yet <code>constexpr</code> where possible.

static const double M_PI = 3.14159;
static constexpr double M_PI = 3.14159;

The use of macros should be kept to a minimum - using a macro in a local scope to reduce boilerplate is acceptable, but macros in headers should only be used when there is no other alternative. Remember to always <code>#undef<code> local macros as soon as they are done being used to prevent accidental name pollution and other issues.

== Include guards ==

Pioneer is (slowly and unofficially) moving away from include guards and using <code>#pragma once</code> as it's easier, less accident-prone (name collisions anyone?), and well supported by all modern compilers. However, we're not rejecting code using include guards instead.

Header include guards should be named for the filename of the header, capitalised, with slashes converted to underscores:

// Ship.h
#ifndef SHIP_H

// WorldView.h
#ifndef WORLDVIEW_H

// graphics/Renderer.h
#ifndef GRAPHICS_RENDERER_H

== Enum types ==

Prefer using C++ style <tt>enum class</tt> declarations when writing new code. They're slightly more difficult to serialize (although only to the extent of requiring a <code>static_cast</code>), but they encourage much more correct code.

No matter which style of enum you're using, try to follow these guidelines:
* Avoid assigning explicit integer values.
* Also avoid values that aren't actually valid for whatever the enum is (though *_MAX to mark the last valid value is usually acceptable).
* If these don't work, chances are what you're trying to do would be better served by multiple enums or even a whole class.

=== C-style Enums ===

Enums are effectively global constants, so should be in full caps. They're prefixed with the name of the enum.

enum Thing {
THING_FOO,
THING_BAR,
THING_BAZ,

THING_MAX
};

=== C++-style Enum Class ===

C++ style enums are closer to classes, and thus they (and their members) should use PascalCase.

<pre>
enum class Thing : uint8_t {
Foo,
Bar,
Baz
};
</pre>

Make sure your enumeration only contains valid values - if you need a <tt>_Max</tt> element, consider using C-style enums scoped in a struct to avoid polluting the global namespace.

<pre>
struct Thing {
enum Thing {
Foo,
Bar,
Baz,

THING_MAX
};
};
</pre>

Coding Conventions

2020-05-11T00:24:00Z

Sturnclaw: Update text and markup

=== Classes ===

Class names should be written in PascalCase like so:

class MyClass {};

Class-private or protected member variables should be prefixed with <tt>m_</tt>, using camelCase:

<pre>
class MyClass {
protected:
int m_someValue;
std::string m_anotherValue;
};
</pre>

Note that to avoid verbosity the above is not followed for structures with public data members, like <tt>vector3</tt>.

All class functions (except those intentionally meant to follow the C++ STL's naming convention) should be written in PascalCase:

<pre>
class MyClass {
public:
void MyFunction() {}
};
</pre>

=== Global variables ===

Global variables must be prefixed with <tt>g_</tt>, and use camelCase:

int g_screenWidth;

Please remember that raw global variables in C++ are considered bad practice; if you're writing code that uses them, you may want to rethink how you're accomplishing your goal.

Variables with static scope should be prefixed with <tt>s_</tt>, and similarly use camelCase:

static int s_classScopeVariable;
// ...
static int s_fileScopeVariable;

== Code Formatting ==

The Pioneer C++ codebase has an enforced common coding style, managed by running the <code>clang-format</code> tool. This is run by the Travis CI provider for all pull requests, and may also be run locally as a [https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks git hook]. If your Pull Request is displaying a red X or a message saying "All checks have failed", it is likely that your code has inadvertently broken the C++ code style that Pioneer uses.

=== Diagnosing Formatting Issues ===

If your Pull Request is in violation of Pioneer's code formatting rules, you can look at the Travis log to find out what parts of your code are specifically to blame. Click "Details" next to "The Travis CI build has failed" at the bottom of the Pull Request page, and select the "Static Checks" job from the resulting page. In the log below, the differences between your code and the correctly formatted code will be listed in [https://linux.die.net/man/1/diff diff(1)] format.

=== Installing a Git Hook ===

Looking at the Travis log to find out what changed is fine and well, but what you really should be doing is using a git hook to validate your code ''before'' you commit your changes. This process is very simple if you are developing on a Mac or Linux system - simply copy the pre-provided git hook into your local repository's <code>hooks/</code> directory. A pre-commit hook is not currently available for Windows systems. If you know how to reliably set one up, you are more than welcome to author it and submit it as a Pull Request.

<pre>
$ cp scripts/clang-format.sh .git/hooks/pre-commit-hook
</pre>

Once you have installed the hook, simply run <code>git commit</code> as normal. If your code doesn't comply with the C++ style rules, it will abort the commit and print the difference between your code and the properly formatted code to the console. If it succeeds, it will open an editor as normal.

If, for some reason, you wish to bypass the validation hook, simply run <code>git commit --no-verify</code>.

=== Applying The Format Changes ===

Once you know which files are improperly formatted, and what changes need to be made to fix them, you have two options. The first option is to manually apply the required changes to your code, and submit them as a new commit. Alternatively, you can use the automatic formatting tool. The interface is simple, presenting you with the list of changes made by clang-format and asking whether you would like to apply them. The invocation is simple as well:

<pre>
$ ./autoformat
</pre>

This will overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, as clang-format has some issues with detecting file types and may occasionally eat your work. Please read the diff and determine which changes will be made. If your version of clang-format is bugged and suggesting destructive changes, manually apply the correct changes and run `git-commit --no-verify` to bypass clang-format entirely.

Pioneer Wiki

2020-02-18T03:14:02Z

Sturnclaw: /* The Pioneer Universe */

Pioneer is a space adventure game set in the Milkyway galaxy at the turn of the 31st century. The game is open-ended, and you are free to explore the millions of star systems in the game. You can land on planets, slingshot past gas giants, and burn yourself to a crisp flying between binary star systems.

If you are new to pioneer you may want to know [[How_to_start|how to start]].

*[http://pioneerspacesim.net/download Download Pioneer] for Windows, Linux and Mac OSX

Please make this wiki nice. Add stuff about mods, dev, whatever. Be awesome! [[Getting_started|How to get started]].

----

{| width="100%"
|-
| style="background:#bbffbb; border:2px solid #99ee99; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Community ===

*[http://pioneerspacesim.net/ Pioneer Space Sim Homepage]
*[https://github.com/pioneerspacesim/pioneer/ Main Github repository]
*[http://spacesimcentral.com/community/pioneer/ Community forum]
*[http://pioneerspacesim.net/forum Developer forum]
*[https://reddit.com/r/pioneerspacesim Pioneer Space Sim on Reddit]
*[https://pioneerspacesim.itch.io/pioneer Pioneer Space Sim on itch]
*[http://webchat.freenode.net/?channels=#pioneer Pioneer Space Sim on IRC]
*[http://twitter.com/pioneerspacesim @pioneerspacesim] on Twitter

----

*[[Manual|Basic Manual]]
*[[Flight_UI|Flight UI]]
*[[Keyboard_and_mouse_controls|Keyboard and mouse controls]]
*[[Tutorials|Tutorials]] (Outdated and WIP)
*[[Mission_Types_and_BBS|Mission Types and BBS]]
*[[Settings_Menu|Settings Menu]]
*[[FAQ|FAQ]]
*[[Media_Coverage|Media Coverage]]

| style="background:#fff9b1; border:2px solid #f0fe66; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |

=== The Pioneer Universe ===

*[[Pioneer_Universe|Pioneer Universe]]
*[[:Category:Ships| Ships]] (work in progress)
*[[:Category:Manufacturers| Manufacturers]] (work in progress)
*[[Places_of_interest|Places of interest]]
*[[Ship_Equipment|Ship Equipment]] (work in progress)

|}

 

{| width="100%"
|-
| style="background:#f0f0ff; border:2px solid #c6c9ff; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |

=== Content Creation ===

*[[Mods|Mods]]
*[[Scripting_and_Mission_Creation|Scripting and Mission Creation]]
*[[Custom_Systems|Custom Systems]]
*[[Design_and_Concept_art|Design and Concept art]]
*[[Modeling,_Texturing,_Graphics_Design|Modeling, Texturing, Graphics Design]]
*[[Music_and_Sound|Music and Sound]]
*[[Translations|Translations]]
*[[Licensing|Licensing]]

| style="background:#fff3e3; border:2px solid #ffc9c9; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Development ===

*[[Design_Scope|Game Scope]]
*[[How_you_can_contribute|How you can contribute]]
*[[Getting_Started_with_Development|Getting Started with Development]]
**[[How_to_communicate|How to communicate]]
**[[Using_git_and_GitHub|Using git and GitHub]]
**[[Code_style|Code style]]
**[[Development_team|Development team]]
**[[Engine_Overview|Engine internals overview]]
*[[Development_Model|Development Model]]
*[[Design_Workflow|Design and Project Management Workflow]]
*[https://github.com/pioneerspacesim/pioneer/issues Issue tracker]
*[[Roadmap|Roadmap]]

|}

Pioneer is brought to you by a flock of [https://github.com/pioneerspacesim/pioneer/blob/master/AUTHORS.txt opensource beardy-weirdies], and is [http://www.gnu.org/licenses/gpl.html Free Software]

'''__NOTOC__'''

Translations

2019-03-22T19:28:06Z

Sturnclaw: /* For mod developers */

All text in Pioneer is translatable, and the game ships with several translations. Here's everything you need to know.

== For translators ==

All our translations are managed through [http://transifex.com Transifex], a free web-based translation service. To start writing translations, sign up there, and then take a look at the [https://www.transifex.com/projects/p/pioneer/ Pioneer project].

Changes to translations are automatically pulled into the master git repo twice per day, and from there to the builds when they're next run.

In Transifex you can subscribe to notifications for the languages or resources you're interested in. When new strings are added or modified, you'll be told about it.

If you want to translate Pioneer to an entirely new language, please [https://pioneerspacesim.net/issues open an issue] on the tracker and someone will create the translation for you.

English is the canonical language for Pioneer. As such, you can't directly modify the english strings through Transifex. If you want to change those, you'll need to make the change in git and submit a pull request like normal.

Untranslated strings will use the value from the English version.

You can leave comments in Transifex to help out other translators. You'll also see any notes left by the developers to help you translate a particular string.

If you're a new translator and you'd like your name included in AUTHORS.txt, please let us know!

== For mod developers ==

Each module gets its own translation resource, called <tt>module-foo</tt>.

To get at the strings for your module, do something like:

local Lang = import("Lang")
local l = Lang.GetResource("module-foo")

Then you can get at the string by its token:

print(l.SOME_TRANSLATED_STRING)

While its possible to load multiple translation resources to share strings, its highly recommended that you don't do that. Stick to your own strings so that you don't have to track changes in other modules. Duplicates across resources are fine. Note that code that uses multiple resources won't be accepted into the main Pioneer repository unless you've checked it with a core developer first and it has a good reason.

Translations are [https://developer.chrome.com/extensions/i18n.html <tt>chrome.i18n</tt> JSON] files. The format is fairly simple - a JSON object with tokens as keys and values of an object with two keys, <tt>message</tt> and <tt>description</tt>. <tt>message</tt> is the text that will appear in the game, while <tt>description</tt> provides instructions for the translator that will be displayed in Transifex. [http://json.org/string.gif Here] is a useful chart showing how characters are interpreted.

If you're submitting code that requires a new language you should only include <tt>en.json</tt>. Please tag '''@impaktor''' in your pull request so they can create a new resource in Transifex and make sure a language update is done at merge. If you don't do this then you'll break the game for non-English users.

== For core developers ==

The <tt>core</tt> resource is magical. If you add a string to it, you also need to add it to <tt>LangStrings.inc.h</tt> and recompile. It will then be available as <tt>Lang::SOME_TRANSLATED_STRING</tt>.

Translations

2019-03-22T19:27:45Z

Sturnclaw: Update instructions for tagging Transifex maintainers.

All text in Pioneer is translatable, and the game ships with several translations. Here's everything you need to know.

== For translators ==

All our translations are managed through [http://transifex.com Transifex], a free web-based translation service. To start writing translations, sign up there, and then take a look at the [https://www.transifex.com/projects/p/pioneer/ Pioneer project].

Changes to translations are automatically pulled into the master git repo twice per day, and from there to the builds when they're next run.

In Transifex you can subscribe to notifications for the languages or resources you're interested in. When new strings are added or modified, you'll be told about it.

If you want to translate Pioneer to an entirely new language, please [https://pioneerspacesim.net/issues open an issue] on the tracker and someone will create the translation for you.

English is the canonical language for Pioneer. As such, you can't directly modify the english strings through Transifex. If you want to change those, you'll need to make the change in git and submit a pull request like normal.

Untranslated strings will use the value from the English version.

You can leave comments in Transifex to help out other translators. You'll also see any notes left by the developers to help you translate a particular string.

If you're a new translator and you'd like your name included in AUTHORS.txt, please let us know!

== For mod developers ==

Each module gets its own translation resource, called <tt>module-foo</tt>.

To get at the strings for your module, do something like:

local Lang = import("Lang")
local l = Lang.GetResource("module-foo")

Then you can get at the string by its token:

print(l.SOME_TRANSLATED_STRING)

While its possible to load multiple translation resources to share strings, its highly recommended that you don't do that. Stick to your own strings so that you don't have to track changes in other modules. Duplicates across resources are fine. Note that code that uses multiple resources won't be accepted into the main Pioneer repository unless you've checked it with a core developer first and it has a good reason.

Translations are [https://developer.chrome.com/extensions/i18n.html <tt>chrome.i18n</tt> JSON] files. The format is fairly simple - a JSON object with tokens as keys and values of an object with two keys, <tt>message</tt> and <tt>description</tt>. <tt>message</tt> is the text that will appear in the game, while <tt>description</tt> provides instructions for the translator that will be displayed in Transifex. [http://json.org/string.gif Here] is a useful chart showing how characters are interpreted.

If you're submitting code that requires a new language you should only include <tt>en.json</tt>. Please tag @impaktor in your pull request so they can create a new resource in Transifex and make sure a language update is done at merge. If you don't do this then you'll break the game for non-English users.

== For core developers ==

The <tt>core</tt> resource is magical. If you add a string to it, you also need to add it to <tt>LangStrings.inc.h</tt> and recompile. It will then be available as <tt>Lang::SOME_TRANSLATED_STRING</tt>.

Pioneer Wiki

2019-03-22T17:22:24Z

Sturnclaw: Add reddit link.

Pioneer is a space adventure game set in the Milkyway galaxy at the turn of the 31st century. The game is open-ended, and you are free to explore the millions of star systems in the game. You can land on planets, slingshot past gas giants, and burn yourself to a crisp flying between binary star systems.

If you are new to pioneer you may want to know [[How_to_start|how to start]].

*[http://pioneerspacesim.net/download Download Pioneer] for Windows, Linux and Mac OSX

Please make this wiki nice. Add stuff about mods, dev, whatever. Be awesome! [[Getting_started|How to get started]].

----

{| width="100%"
|-
| style="background:#bbffbb; border:2px solid #99ee99; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Community ===

*[http://pioneerspacesim.net/ Pioneer Space Sim Homepage]
*[https://github.com/pioneerspacesim/pioneer/ Main Github repository]
*[http://spacesimcentral.com/ssc/forum/23-pioneer/ Community forum]
*[http://pioneerspacesim.net/forum Developer forum]
*[https://reddit.com/r/pioneerspacesim Pioneer Space Sim on Reddit]
*[http://webchat.freenode.net/?channels=#pioneer Pioneer Space Sim on IRC]
*[http://twitter.com/pioneerspacesim @pioneerspacesim] on Twitter

----

*[[Manual|Basic Manual]]
*[[Flight_UI|Flight UI]]
*[[Keyboard_and_mouse_controls|Keyboard and mouse controls]]
*[[Tutorials|Tutorials]] (Outdated and WIP)
*[[Mission_Types_and_BBS|Mission Types and BBS]]
*[[Settings_Menu|Settings Menu]]
*[[FAQ|FAQ]]
*[[Media_Coverage|Media Coverage]]

| style="background:#fff9b1; border:2px solid #f0fe66; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== The Pioneer Universe ===

*[[Pioneer_Universe|Pioneer Universe]]
*[http://pioneerwiki.com/wiki/Category:Ships Ships] (work in progress)
*[http://pioneerwiki.com/wiki/Category:Manufacturers Manufacturers] (work in progress)
*[[Places_of_interest|Places of interest]]
*[[Ship_Equipment|Ship Equipment]] (work in progress)

|}

 

{| width="100%"
|-
| style="background:#f0f0ff; border:2px solid #c6c9ff; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Content Creation ===

*[[Mods|Mods]]
*[[Scripting_and_Mission_Creation|Scripting and Mission Creation]]
*[[Custom_Systems|Custom Systems]]
*[[Design_and_Concept_art|Design and Concept art]]
*[[Modeling,_Texturing,_Graphics_Design|Modeling, Texturing, Graphics Design]]
*[[Music_and_Sound|Music and Sound]]
*[[Translations|Translations]]
*[[Licensing|Licensing]]

| style="background:#fff3e3; border:2px solid #ffc9c9; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Development ===

*[[Design_Scope|Game Scope]]
*[[How_you_can_contribute|How you can contribute]]
*[[Getting_Started_with_Development|Getting Started with Development]]
**[[How_to_communicate|How to communicate]]
**[[Using_git_and_GitHub|Using git and GitHub]]
**[[Code_style|Code style]]
**[[Development_team|Development team]]
**[[Engine_Overview|Engine internals overview]]
*[[Development_Model|Development Model]]
*[[Design_Workflow|Design and Project Management Workflow]]
*[https://github.com/pioneerspacesim/pioneer/issues Issue tracker]
*[[Roadmap|Roadmap]]

|}

Pioneer is brought to you by a flock of [https://github.com/pioneerspacesim/pioneer/blob/master/AUTHORS.txt opensource beardy-weirdies], and is [http://www.gnu.org/licenses/gpl.html Free Software]

'''__NOTOC__'''

Pioneer Wiki

2019-03-22T03:21:48Z

Sturnclaw: Google+ will 404 in a week, and nobody's used the Pioneer page in four years. Removing now before I forget.

Pioneer is a space adventure game set in the Milkyway galaxy at the turn of the 31st century. The game is open-ended, and you are free to explore the millions of star systems in the game. You can land on planets, slingshot past gas giants, and burn yourself to a crisp flying between binary star systems.

If you are new to pioneer you may want to know [[How_to_start|how to start]].

*[http://pioneerspacesim.net/download Download Pioneer] for Windows, Linux and Mac OSX

Please make this wiki nice. Add stuff about mods, dev, whatever. Be awesome! [[Getting_started|How to get started]].

----

{| width="100%"
|-
| style="background:#bbffbb; border:2px solid #99ee99; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Community ===

*[http://pioneerspacesim.net/ Pioneer Space Sim Homepage]
*[https://github.com/pioneerspacesim/pioneer/ Main Github repository]
*[http://spacesimcentral.com/ssc/forum/23-pioneer/ Community forum]
*[http://pioneerspacesim.net/forum Developer forum]
*[http://webchat.freenode.net/?channels=#pioneer Pioneer Space Sim on IRC]
*[http://twitter.com/pioneerspacesim @pioneerspacesim] on Twitter

----

*[[Manual|Basic Manual]]
*[[Flight_UI|Flight UI]]
*[[Keyboard_and_mouse_controls|Keyboard and mouse controls]]
*[[Tutorials|Tutorials]] (Outdated and WIP)
*[[Mission_Types_and_BBS|Mission Types and BBS]]
*[[Settings_Menu|Settings Menu]]
*[[FAQ|FAQ]]
*[[Media_Coverage|Media Coverage]]

| style="background:#fff9b1; border:2px solid #f0fe66; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== The Pioneer Universe ===

*[[Pioneer_Universe|Pioneer Universe]]
*[http://pioneerwiki.com/wiki/Category:Ships Ships] (work in progress)
*[http://pioneerwiki.com/wiki/Category:Manufacturers Manufacturers] (work in progress)
*[[Places_of_interest|Places of interest]]
*[[Ship_Equipment|Ship Equipment]] (work in progress)

|}

 

{| width="100%"
|-
| style="background:#f0f0ff; border:2px solid #c6c9ff; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Content Creation ===

*[[Mods|Mods]]
*[[Scripting_and_Mission_Creation|Scripting and Mission Creation]]
*[[Custom_Systems|Custom Systems]]
*[[Design_and_Concept_art|Design and Concept art]]
*[[Modeling,_Texturing,_Graphics_Design|Modeling, Texturing, Graphics Design]]
*[[Music_and_Sound|Music and Sound]]
*[[Translations|Translations]]
*[[Licensing|Licensing]]

| style="background:#fff3e3; border:2px solid #ffc9c9; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Development ===

*[[Design_Scope|Game Scope]]
*[[How_you_can_contribute|How you can contribute]]
*[[Getting_Started_with_Development|Getting Started with Development]]
**[[How_to_communicate|How to communicate]]
**[[Using_git_and_GitHub|Using git and GitHub]]
**[[Code_style|Code style]]
**[[Development_team|Development team]]
**[[Engine_Overview|Engine internals overview]]
*[[Development_Model|Development Model]]
*[[Design_Workflow|Design and Project Management Workflow]]
*[https://github.com/pioneerspacesim/pioneer/issues Issue tracker]
*[[Roadmap|Roadmap]]

|}

Pioneer is brought to you by a flock of [https://github.com/pioneerspacesim/pioneer/blob/master/AUTHORS.txt opensource beardy-weirdies], and is [http://www.gnu.org/licenses/gpl.html Free Software]

'''__NOTOC__'''

User:Sturnclaw

2019-03-15T21:07:13Z

Sturnclaw: /* Gameplay: */

Hello! My name is Sturnclaw. Your code offends me. Prepare to die.

In more serious news, I'm known as Sturnclaw around here. In demeanor, I'm pretty much your typical overconfident software engineer who thinks he can do anything given enough time and sauerkraut – I'll leave the verification of that claim up to the reader.

A cursory search will reveal that I'm the owner and head of Web eWorks, LTD, and when I'm not busy with that or one of a number of side projects, I work on Pioneer to brush up my C++ skills.

You can find me on Github as [https://github.com/web-eworks Web eWorks], or on IRC as sturnclaw.

== The List ==

Upon the recommendation of several members of the team, I have begun to curate The List, stored right here on this page.

What is "The List", you ask? The List is basically a copy of Pioneer's roadmap, kept fairly current to the latest IRC <s>fantasizing</s> plans, and annotated with my thoughts and recommendations for implementation. It is estimated that completing all of the items on The List will take between 5 and 15 person-years of development work, so if you want to implement something here, go right ahead.

Without further ado, I present The List:

=== Core Tech: ===

==== Entity Component System (ECS) Model ====
Convert the Pioneer codebase to use a composition-based model instead of an inheritance-based model.
* The rationale behind this decision is that an inheritance-based architecture for gameplay objects is generally unsustainable without some form of composition, especially so when mods are involved - what if your mod wants to add a different implementation of a hyperdrive?
* This will be a multi-step process:
** Implement some minor features using the ECS paradigm to get started and evaluate requirements. '''Working'''
** Drive the new ECS-based features from existing code as a temporary measure. '''Working'''
** Convert a major feature (Ship, BodyOnPlanet, etc) to use the ECS.
** Continue converting major features until all applicable areas of the code are converted.

==== Input System ====
Before I started working on Pioneer, the input system was particularly archaic; inputs were defined with macros in a single file that got <nowiki>#include</nowiki>d into about 4 different files and compiled into the binary - needless to say, if you wanted a new input axis or action, you had to recompile the entire game.

The input system is currently being refactored into a modular, moddable system which supports sharing axes between systems and modules and defining entirely new axes and actions in mods.

This change is about half done - the technical underpinnings of the system are mostly finished, and all that's left is to expose it to Lua.

Planned Features:
* Modular, Lua-exposed input system '''WORKING'''
* Key-chord inputs, allowing arbitrary modifier keys / buttons. A software "pinkie switch" if you will.
* Touchscreen input for camera and flight controls. (Investigate: virtual joysticks or whole-screen mouse emulation?)

=== Lua Engine ===
Coming on the heels of the input changes are improvements to Pioneer's Lua engine. At current, Pioneer is using its own feature-incomplete version of <nowiki>require()</nowiki> (used as <nowiki>import()</nowiki>), which supports a very limited method of calling other code files. Additionally, the C++ side of the Lua interface has issues with handling Lua errors - if C++ calls a lua function that errors, the whole engine terminates with an error.

There are several goals to accomplish here, but the major two are:
* Update <nowiki>import()</nowiki> to support Lua 5.2+ style "module.submodule" syntax '''(DONE)''' and implicit "init.lua" support.
* Make throwing a Lua error safe with regards to C++ code, and support arbitrarily disabling a Lua module if it is throwing an error.
** E.g. if a specific part of the UI throws an error, silently catch it and log it. If it keeps throwing errors, disable the module and inform the user. This is going to require some significant work, but it will make the modding and content-creation ecosystem much more user-friendly.

Tangentially to the ECS changes, we need a better method of binding C++ code and data to Lua. Currently the hand-written method is serviceable, but it is akin to "implementing the same thing twice", doubling the workload for anyone wanting to add something new.
* Add an automatic solution for binding C++ code to Lua, capable of auto-generating bindings for properties, methods, and POD-structs and full LuaObject classes.
** Use a Lua script to scan C++ files for annotations, generating bindings based upon annotated properties and methods.
** To avoid re-inventing the wheel, generate C++ files that make heavy use of templates to pass data back and forth from Lua. This will allow programmers to do sanity-checking in template specializations, and create a common convention for binding data to Lua.

=== Gameplay: ===

There are a ''huge'' number of new features and wild gameplay ideas that I and others would really like to see added to the game, but this is a more reasonable list of features that can actually be implemented with a few weeks of work.

* Refactor the camera / view system to better support inputs, allow arbitrary spectator / debug cameras for editor mode, enable first-person and turret cameras.
** Add a "camera offset" axis for internal / cockpit view that can be hooked up to headtracking. '''In Testing'''
** Make the existing camera system use the new InputFrames for input. '''In Testing'''
** Decouple camera systems from the concept of a ship to make them suitable for debug/flying cameras. '''Evaluating'''
** Add cameras for turrets. '''Stalled on Dependency'''
* Completely rewrite the weapons systems to support arbitrary guns and turrets, as well as a better loadout system.
* Rework drag and atmospheric heating to be actually accurate, implement atmospheric lift so aerodynamic ships can fly. '''WORKING, w/ WKFO'''
* Add airframe damage due to excessive G-force and/or dynamic pressure when flying in atmosphere.
** Possibly damage specific components (landing gear, control surfaces, etc) reducing their effectiveness and/or destroying them.

=== Rendering: ===

==== PBR Rendering Engine ====

Convert Pioneer to a Clustered Forward or Clustered Deferred rendering model. This change needs to implement support for numerous lights, mesh decals ala Star Citizen, accurate terrain rendering with high-res texturing support via material layering and distance-dependent detail texturing, a full postprocessing chain including bloom, chromatic aberration, motion blur, and an AO implementation (perhaps an HBAO or SSAO variant), support for atmospheric shading, etc.

Reference:
* [https://turanszkij.wordpress.com/2017/10/12/forward-decal-rendering/ Forward+ Decal Rendering]
* [https://google.github.io/filament/Filament.md.html Filament Renderer], an open-source mobile-capable Clustered Forward PBR renderer, with accompanying whitepaper.
* [http://www.cse.chalmers.se/~uffe/clustered_shading_preprint.pdf A paper on clustered rendering]
* [http://www.thetenthplanet.de/archives/4519 Atmospheric Scattering] with link to implementation.

'''Clouds'''

Possibly using a low-resolution voxelized implementation, atmospheric clouds are a planned feature. They'd need to support transparency, layer over each other without killing performance, and look at least moderately good. Flat clouds are also required when looking at a planet from orbit, which could be static textures or generated from a basic weather simulation for believable construction.

''' Mesh Decals '''

TODO: link in nozmajner's ship decal work, pontificate about supporting that engine-side.

=== Content: ===

* Finish modelling and texturing the Sador Heavy Fighter, including setting it up to use turrets and the new gun / missile system.

User:Sturnclaw

2019-03-14T18:13:22Z

Sturnclaw: /* Rendering: */

Hello! My name is Sturnclaw. Your code offends me. Prepare to die.

In more serious news, I'm known as Sturnclaw around here. In demeanor, I'm pretty much your typical overconfident software engineer who thinks he can do anything given enough time and sauerkraut – I'll leave the verification of that claim up to the reader.

A cursory search will reveal that I'm the owner and head of Web eWorks, LTD, and when I'm not busy with that or one of a number of side projects, I work on Pioneer to brush up my C++ skills.

You can find me on Github as [https://github.com/web-eworks Web eWorks], or on IRC as sturnclaw.

== The List ==

Upon the recommendation of several members of the team, I have begun to curate The List, stored right here on this page.

What is "The List", you ask? The List is basically a copy of Pioneer's roadmap, kept fairly current to the latest IRC <s>fantasizing</s> plans, and annotated with my thoughts and recommendations for implementation. It is estimated that completing all of the items on The List will take between 5 and 15 person-years of development work, so if you want to implement something here, go right ahead.

Without further ado, I present The List:

=== Core Tech: ===

==== Entity Component System (ECS) Model ====
Convert the Pioneer codebase to use a composition-based model instead of an inheritance-based model.
* The rationale behind this decision is that an inheritance-based architecture for gameplay objects is generally unsustainable without some form of composition, especially so when mods are involved - what if your mod wants to add a different implementation of a hyperdrive?
* This will be a multi-step process:
** Implement some minor features using the ECS paradigm to get started and evaluate requirements. '''Working'''
** Drive the new ECS-based features from existing code as a temporary measure. '''Working'''
** Convert a major feature (Ship, BodyOnPlanet, etc) to use the ECS.
** Continue converting major features until all applicable areas of the code are converted.

==== Input System ====
Before I started working on Pioneer, the input system was particularly archaic; inputs were defined with macros in a single file that got <nowiki>#include</nowiki>d into about 4 different files and compiled into the binary - needless to say, if you wanted a new input axis or action, you had to recompile the entire game.

The input system is currently being refactored into a modular, moddable system which supports sharing axes between systems and modules and defining entirely new axes and actions in mods.

This change is about half done - the technical underpinnings of the system are mostly finished, and all that's left is to expose it to Lua.

Planned Features:
* Modular, Lua-exposed input system '''WORKING'''
* Key-chord inputs, allowing arbitrary modifier keys / buttons. A software "pinkie switch" if you will.
* Touchscreen input for camera and flight controls. (Investigate: virtual joysticks or whole-screen mouse emulation?)

=== Lua Engine ===
Coming on the heels of the input changes are improvements to Pioneer's Lua engine. At current, Pioneer is using its own feature-incomplete version of <nowiki>require()</nowiki> (used as <nowiki>import()</nowiki>), which supports a very limited method of calling other code files. Additionally, the C++ side of the Lua interface has issues with handling Lua errors - if C++ calls a lua function that errors, the whole engine terminates with an error.

There are several goals to accomplish here, but the major two are:
* Update <nowiki>import()</nowiki> to support Lua 5.2+ style "module.submodule" syntax '''(DONE)''' and implicit "init.lua" support.
* Make throwing a Lua error safe with regards to C++ code, and support arbitrarily disabling a Lua module if it is throwing an error.
** E.g. if a specific part of the UI throws an error, silently catch it and log it. If it keeps throwing errors, disable the module and inform the user. This is going to require some significant work, but it will make the modding and content-creation ecosystem much more user-friendly.

Tangentially to the ECS changes, we need a better method of binding C++ code and data to Lua. Currently the hand-written method is serviceable, but it is akin to "implementing the same thing twice", doubling the workload for anyone wanting to add something new.
* Add an automatic solution for binding C++ code to Lua, capable of auto-generating bindings for properties, methods, and POD-structs and full LuaObject classes.
** Use a Lua script to scan C++ files for annotations, generating bindings based upon annotated properties and methods.
** To avoid re-inventing the wheel, generate C++ files that make heavy use of templates to pass data back and forth from Lua. This will allow programmers to do sanity-checking in template specializations, and create a common convention for binding data to Lua.

=== Gameplay: ===

* Refactor the camera / view system to better support inputs, allow arbitrary spectator / debug cameras for editor mode, enable first-person and turret cameras.
** Add a "camera offset" axis for internal / cockpit view that can be hooked up to headtracking. '''In Testing'''
** Make the existing camera system use the new InputFrames for input. '''In Testing'''
** Decouple camera systems from the concept of a ship to make them suitable for debug/flying cameras. '''Evaluating'''
** Add cameras for turrets. '''Stalled on Dependency'''
* Completely rewrite the weapons systems to support arbitrary guns and turrets, as well as a better loadout system.

=== Rendering: ===

==== PBR Rendering Engine ====

Convert Pioneer to a Clustered Forward or Clustered Deferred rendering model. This change needs to implement support for numerous lights, mesh decals ala Star Citizen, accurate terrain rendering with high-res texturing support via material layering and distance-dependent detail texturing, a full postprocessing chain including bloom, chromatic aberration, motion blur, and an AO implementation (perhaps an HBAO or SSAO variant), support for atmospheric shading, etc.

Reference:
* [https://turanszkij.wordpress.com/2017/10/12/forward-decal-rendering/ Forward+ Decal Rendering]
* [https://google.github.io/filament/Filament.md.html Filament Renderer], an open-source mobile-capable Clustered Forward PBR renderer, with accompanying whitepaper.
* [http://www.cse.chalmers.se/~uffe/clustered_shading_preprint.pdf A paper on clustered rendering]
* [http://www.thetenthplanet.de/archives/4519 Atmospheric Scattering] with link to implementation.

'''Clouds'''

Possibly using a low-resolution voxelized implementation, atmospheric clouds are a planned feature. They'd need to support transparency, layer over each other without killing performance, and look at least moderately good. Flat clouds are also required when looking at a planet from orbit, which could be static textures or generated from a basic weather simulation for believable construction.

''' Mesh Decals '''

TODO: link in nozmajner's ship decal work, pontificate about supporting that engine-side.

=== Content: ===

* Finish modelling and texturing the Sador Heavy Fighter, including setting it up to use turrets and the new gun / missile system.

User:Sturnclaw

2019-03-14T18:12:55Z

Sturnclaw: /* Rendering: */

Hello! My name is Sturnclaw. Your code offends me. Prepare to die.

In more serious news, I'm known as Sturnclaw around here. In demeanor, I'm pretty much your typical overconfident software engineer who thinks he can do anything given enough time and sauerkraut – I'll leave the verification of that claim up to the reader.

A cursory search will reveal that I'm the owner and head of Web eWorks, LTD, and when I'm not busy with that or one of a number of side projects, I work on Pioneer to brush up my C++ skills.

You can find me on Github as [https://github.com/web-eworks Web eWorks], or on IRC as sturnclaw.

== The List ==

Upon the recommendation of several members of the team, I have begun to curate The List, stored right here on this page.

What is "The List", you ask? The List is basically a copy of Pioneer's roadmap, kept fairly current to the latest IRC <s>fantasizing</s> plans, and annotated with my thoughts and recommendations for implementation. It is estimated that completing all of the items on The List will take between 5 and 15 person-years of development work, so if you want to implement something here, go right ahead.

Without further ado, I present The List:

=== Core Tech: ===

==== Entity Component System (ECS) Model ====
Convert the Pioneer codebase to use a composition-based model instead of an inheritance-based model.
* The rationale behind this decision is that an inheritance-based architecture for gameplay objects is generally unsustainable without some form of composition, especially so when mods are involved - what if your mod wants to add a different implementation of a hyperdrive?
* This will be a multi-step process:
** Implement some minor features using the ECS paradigm to get started and evaluate requirements. '''Working'''
** Drive the new ECS-based features from existing code as a temporary measure. '''Working'''
** Convert a major feature (Ship, BodyOnPlanet, etc) to use the ECS.
** Continue converting major features until all applicable areas of the code are converted.

==== Input System ====
Before I started working on Pioneer, the input system was particularly archaic; inputs were defined with macros in a single file that got <nowiki>#include</nowiki>d into about 4 different files and compiled into the binary - needless to say, if you wanted a new input axis or action, you had to recompile the entire game.

The input system is currently being refactored into a modular, moddable system which supports sharing axes between systems and modules and defining entirely new axes and actions in mods.

This change is about half done - the technical underpinnings of the system are mostly finished, and all that's left is to expose it to Lua.

Planned Features:
* Modular, Lua-exposed input system '''WORKING'''
* Key-chord inputs, allowing arbitrary modifier keys / buttons. A software "pinkie switch" if you will.
* Touchscreen input for camera and flight controls. (Investigate: virtual joysticks or whole-screen mouse emulation?)

=== Lua Engine ===
Coming on the heels of the input changes are improvements to Pioneer's Lua engine. At current, Pioneer is using its own feature-incomplete version of <nowiki>require()</nowiki> (used as <nowiki>import()</nowiki>), which supports a very limited method of calling other code files. Additionally, the C++ side of the Lua interface has issues with handling Lua errors - if C++ calls a lua function that errors, the whole engine terminates with an error.

There are several goals to accomplish here, but the major two are:
* Update <nowiki>import()</nowiki> to support Lua 5.2+ style "module.submodule" syntax '''(DONE)''' and implicit "init.lua" support.
* Make throwing a Lua error safe with regards to C++ code, and support arbitrarily disabling a Lua module if it is throwing an error.
** E.g. if a specific part of the UI throws an error, silently catch it and log it. If it keeps throwing errors, disable the module and inform the user. This is going to require some significant work, but it will make the modding and content-creation ecosystem much more user-friendly.

Tangentially to the ECS changes, we need a better method of binding C++ code and data to Lua. Currently the hand-written method is serviceable, but it is akin to "implementing the same thing twice", doubling the workload for anyone wanting to add something new.
* Add an automatic solution for binding C++ code to Lua, capable of auto-generating bindings for properties, methods, and POD-structs and full LuaObject classes.
** Use a Lua script to scan C++ files for annotations, generating bindings based upon annotated properties and methods.
** To avoid re-inventing the wheel, generate C++ files that make heavy use of templates to pass data back and forth from Lua. This will allow programmers to do sanity-checking in template specializations, and create a common convention for binding data to Lua.

=== Gameplay: ===

* Refactor the camera / view system to better support inputs, allow arbitrary spectator / debug cameras for editor mode, enable first-person and turret cameras.
** Add a "camera offset" axis for internal / cockpit view that can be hooked up to headtracking. '''In Testing'''
** Make the existing camera system use the new InputFrames for input. '''In Testing'''
** Decouple camera systems from the concept of a ship to make them suitable for debug/flying cameras. '''Evaluating'''
** Add cameras for turrets. '''Stalled on Dependency'''
* Completely rewrite the weapons systems to support arbitrary guns and turrets, as well as a better loadout system.

=== Rendering: ===

==== PBR Rendering Engine ====

Convert Pioneer to a Clustered Forward or Clustered Deferred rendering model. This change needs to implement support for numerous lights, mesh decals ala Star Citizen, accurate terrain rendering with high-res texturing support via material layering and distance-dependent detail texturing, a full postprocessing chain including bloom, chromatic aberration, motion blur, and an AO implementation (perhaps an HBAO or SSAO variant), support for atmospheric shading, etc.

Reference:
* [https://turanszkij.wordpress.com/2017/10/12/forward-decal-rendering/ Forward+ Decal Rendering]
* [https://google.github.io/filament/Filament.md.html Filament Renderer], an open-source mobile-capable Clustered Forward PBR renderer, with accompanying whitepaper.
* [http://www.cse.chalmers.se/~uffe/clustered_shading_preprint.pdf A paper on clustered rendering]
* [http://www.thetenthplanet.de/archives/4519 Atmospheric Scattering] with link to implementation.

'''Clouds'''

Possibly using a low-resolution voxelized implementation, atmospheric clouds are a planned feature. They'd need to support transparency, layer over each other without killing performance, and look at least moderately good. Flat clouds are also required when looking at a planet from orbit, which could be static textures or generated from a basic weather simulation for believable construction.

==== Mesh Decals ====

TODO: link in nozmajner's ship decal work, pontificate about supporting that engine-side.

=== Content: ===

* Finish modelling and texturing the Sador Heavy Fighter, including setting it up to use turrets and the new gun / missile system.

User:Sturnclaw

2019-03-14T18:03:04Z

Sturnclaw: /* Input System */

Hello! My name is Sturnclaw. Your code offends me. Prepare to die.

In more serious news, I'm known as Sturnclaw around here. In demeanor, I'm pretty much your typical overconfident software engineer who thinks he can do anything given enough time and sauerkraut – I'll leave the verification of that claim up to the reader.

A cursory search will reveal that I'm the owner and head of Web eWorks, LTD, and when I'm not busy with that or one of a number of side projects, I work on Pioneer to brush up my C++ skills.

You can find me on Github as [https://github.com/web-eworks Web eWorks], or on IRC as sturnclaw.

== The List ==

Upon the recommendation of several members of the team, I have begun to curate The List, stored right here on this page.

What is "The List", you ask? The List is basically a copy of Pioneer's roadmap, kept fairly current to the latest IRC <s>fantasizing</s> plans, and annotated with my thoughts and recommendations for implementation. It is estimated that completing all of the items on The List will take between 5 and 15 person-years of development work, so if you want to implement something here, go right ahead.

Without further ado, I present The List:

=== Core Tech: ===

==== Entity Component System (ECS) Model ====
Convert the Pioneer codebase to use a composition-based model instead of an inheritance-based model.
* The rationale behind this decision is that an inheritance-based architecture for gameplay objects is generally unsustainable without some form of composition, especially so when mods are involved - what if your mod wants to add a different implementation of a hyperdrive?
* This will be a multi-step process:
** Implement some minor features using the ECS paradigm to get started and evaluate requirements. '''Working'''
** Drive the new ECS-based features from existing code as a temporary measure. '''Working'''
** Convert a major feature (Ship, BodyOnPlanet, etc) to use the ECS.
** Continue converting major features until all applicable areas of the code are converted.

==== Input System ====
Before I started working on Pioneer, the input system was particularly archaic; inputs were defined with macros in a single file that got <nowiki>#include</nowiki>d into about 4 different files and compiled into the binary - needless to say, if you wanted a new input axis or action, you had to recompile the entire game.

The input system is currently being refactored into a modular, moddable system which supports sharing axes between systems and modules and defining entirely new axes and actions in mods.

This change is about half done - the technical underpinnings of the system are mostly finished, and all that's left is to expose it to Lua.

Planned Features:
* Modular, Lua-exposed input system '''WORKING'''
* Key-chord inputs, allowing arbitrary modifier keys / buttons. A software "pinkie switch" if you will.
* Touchscreen input for camera and flight controls. (Investigate: virtual joysticks or whole-screen mouse emulation?)

=== Lua Engine ===
Coming on the heels of the input changes are improvements to Pioneer's Lua engine. At current, Pioneer is using its own feature-incomplete version of <nowiki>require()</nowiki> (used as <nowiki>import()</nowiki>), which supports a very limited method of calling other code files. Additionally, the C++ side of the Lua interface has issues with handling Lua errors - if C++ calls a lua function that errors, the whole engine terminates with an error.

There are several goals to accomplish here, but the major two are:
* Update <nowiki>import()</nowiki> to support Lua 5.2+ style "module.submodule" syntax '''(DONE)''' and implicit "init.lua" support.
* Make throwing a Lua error safe with regards to C++ code, and support arbitrarily disabling a Lua module if it is throwing an error.
** E.g. if a specific part of the UI throws an error, silently catch it and log it. If it keeps throwing errors, disable the module and inform the user. This is going to require some significant work, but it will make the modding and content-creation ecosystem much more user-friendly.

Tangentially to the ECS changes, we need a better method of binding C++ code and data to Lua. Currently the hand-written method is serviceable, but it is akin to "implementing the same thing twice", doubling the workload for anyone wanting to add something new.
* Add an automatic solution for binding C++ code to Lua, capable of auto-generating bindings for properties, methods, and POD-structs and full LuaObject classes.
** Use a Lua script to scan C++ files for annotations, generating bindings based upon annotated properties and methods.
** To avoid re-inventing the wheel, generate C++ files that make heavy use of templates to pass data back and forth from Lua. This will allow programmers to do sanity-checking in template specializations, and create a common convention for binding data to Lua.

=== Gameplay: ===

* Refactor the camera / view system to better support inputs, allow arbitrary spectator / debug cameras for editor mode, enable first-person and turret cameras.
** Add a "camera offset" axis for internal / cockpit view that can be hooked up to headtracking. '''In Testing'''
** Make the existing camera system use the new InputFrames for input. '''In Testing'''
** Decouple camera systems from the concept of a ship to make them suitable for debug/flying cameras. '''Evaluating'''
** Add cameras for turrets. '''Stalled on Dependency'''
* Completely rewrite the weapons systems to support arbitrary guns and turrets, as well as a better loadout system.

=== Rendering: ===

==== PBR Rendering Engine ====

Convert Pioneer to a Clustered Forward or Clustered Deferred rendering model. This change needs to implement support for numerous lights, mesh decals ala Star Citizen, accurate terrain rendering with high-res texturing support via material layering and distance-dependent detail texturing, a full postprocessing chain including bloom, chromatic aberration, motion blur, and an AO implementation (perhaps an HBAO or SSAO variant), support for atmospheric shading, etc.

Reference:
* [https://turanszkij.wordpress.com/2017/10/12/forward-decal-rendering/ Forward+ Decal Rendering]
* [https://google.github.io/filament/Filament.md.html Filament Renderer], an open-source mobile-capable Clustered Forward PBR renderer, with accompanying whitepaper.
* [http://www.cse.chalmers.se/~uffe/clustered_shading_preprint.pdf A paper on clustered rendering]
* [http://www.thetenthplanet.de/archives/4519 Atmospheric Scattering] with link to implementation.

==== Mesh Decals ====

TODO: link in nozmajner's ship decal work, pontificate about supporting that engine-side.

=== Content: ===

* Finish modelling and texturing the Sador Heavy Fighter, including setting it up to use turrets and the new gun / missile system.

User:Sturnclaw

2019-03-10T00:39:27Z

Sturnclaw: /* Lua Engine */

User:Sturnclaw

2019-03-10T00:35:12Z

Sturnclaw:

User:Sturnclaw

2019-03-10T00:29:28Z

Sturnclaw:

Coding Conventions

2019-02-16T03:00:24Z

Sturnclaw: Updated clang-format instructions.

=== Classes ===

Class names in camel case starting with upper case like so:

<tt>class MyClass {};</tt>

Class member variables prefixed with <tt>m_</tt>, camel case starting with lower case:

<pre>
class MyClass {
public:
int m_someValue;
std::string m_anotherValue;
};
</pre>

Note that to avoid verbosity the above is not followed for classes that are used more like structs, like vector3.

Class functions should be camel case starting with upper case:

<pre>
class MyClass {
public:
void MyFunction() {}
};
</pre>

=== Global variables ===

Global variables must be prefixed with <tt>g_</tt>, and use camel case starting with lower case:

<tt>int g_screenWidth;</tt>

Variables with static scope should be prefixed with <tt>s_</tt>:

<tt>static int s_someGlobalForJustThisFile;</tt>

== Code Formatting ==

The Pioneer C++ codebase has an enforced common coding style, managed by running the <code>clang-format</code> tool. This is run by the Travis CI provider for all pull requests, and may also be run locally as a [https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks git hook]. If your Pull Request is displaying a red X or a message saying "All checks have failed", it is likely that your code has inadvertently broken the C++ code style that Pioneer uses.

=== Diagnosing Formatting Issues ===

If your Pull Request is in violation of Pioneer's code formatting rules, you can look at the Travis log to find out what parts of your code are specifically to blame. Click "Details" next to "The Travis CI build has failed" at the bottom of the Pull Request page, and select the "Static Checks" job from the resulting page. In the log below, the differences between your code and the correctly formatted code will be listed in [https://linux.die.net/man/1/diff diff(1)] format.

=== Installing a Git Hook ===

Looking at the Travis log to find out what changed is fine and well, but what you really should be doing is using a git hook to validate your code ''before'' you commit your changes. This process is very simple if you are developing on a Mac or Linux system - simply copy the pre-provided git hook into your local repository's <code>hooks/</code> directory. A pre-commit hook is not currently available for Windows systems. If you know how to reliably set one up, you are more than welcome to author it and submit it as a Pull Request.

<pre>
$ cp scripts/clang-format.sh .git/hooks/pre-commit-hook
</pre>

Once you have installed the hook, simply run <code>git commit</code> as normal. If your code doesn't comply with the C++ style rules, it will abort the commit and print the difference between your code and the properly formatted code to the console. If it succeeds, it will open an editor as normal.

If, for some reason, you wish to bypass the validation hook, simply run <code>git commit --no-verify</code>.

=== Applying The Format Changes ===

Once you know which files are improperly formatted, and what changes need to be made to fix them, you have two options. The first option is to manually apply the required changes to your code, and submit them as a new commit. Alternatively, you can use the automatic formatting tool. The interface is simple, presenting you with the list of changes made by clang-format and asking whether you would like to apply them. The invocation is simple as well:

<pre>
$ ./autoformat
</pre>

This will overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, as clang-format has some issues with detecting file types and may occasionally eat your work. Please read the diff and determine which changes will be made. If your version of clang-format is bugged and suggesting destructive changes, manually apply the correct changes and run `git-commit --no-verify` to bypass clang-format entirely.

User:Sturnclaw

2019-02-16T00:41:12Z

Sturnclaw:

Coding Conventions

2019-01-07T02:09:05Z

Sturnclaw: Add details on clang-format and the pre-commit hook.

=== Classes ===

Class names in camel case starting with upper case like so:

<tt>class MyClass {};</tt>

Class member variables prefixed with <tt>m_</tt>, camel case starting with lower case:

<pre>
class MyClass {
public:
int m_someValue;
std::string m_anotherValue;
};
</pre>

Note that to avoid verbosity the above is not followed for classes that are used more like structs, like vector3.

Class functions should be camel case starting with upper case:

<pre>
class MyClass {
public:
void MyFunction() {}
};
</pre>

=== Global variables ===

Global variables must be prefixed with <tt>g_</tt>, and use camel case starting with lower case:

<tt>int g_screenWidth;</tt>

Variables with static scope should be prefixed with <tt>s_</tt>:

<tt>static int s_someGlobalForJustThisFile;</tt>

== Code Formatting ==

The Pioneer C++ codebase has an enforced common coding style, managed by running the <code>clang-format</code> tool. This is run by the Travis CI provider for all pull requests, and may also be run locally as a [https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks git hook]. If your Pull Request is displaying a red X or a message saying "All checks have failed", it is likely that your code has inadvertently broken the C++ code style that Pioneer uses.

=== Diagnosing Formatting Issues ===

If your Pull Request is in violation of Pioneer's code formatting rules, you can look at the Travis log to find out what parts of your code are specifically to blame. Click "Details" next to "The Travis CI build has failed" at the bottom of the Pull Request page, and select the "Static Checks" job from the resulting page. In the log below, the differences between your code and the correctly formatted code will be listed in [https://linux.die.net/man/1/diff diff(1)] format.

=== Installing a Git Hook ===

Looking at the Travis log to find out what changed is fine and well, but what you really should be doing is using a git hook to validate your code ''before'' you commit your changes. This process is very simple if you are developing on a Mac or Linux system - simply copy the pre-provided git hook into your local repository's <code>hooks/</code> directory. A pre-commit hook is not currently available for Windows systems. If you know how to reliably set one up, you are more than welcome to author it and submit it as a Pull Request.

<pre>
$ cp scripts/pre-commit-hook.sh .git/hooks/pre-commit-hook
</pre>

Once you have installed the hook, simply run <code>git commit</code> as normal. If your code doesn't comply with the C++ style rules, it will abort the commit and print the difference between your code and the properly formatted code to the console. If it succeeds, it will open an editor as normal.

If, for some reason, you wish to bypass the validation hook, simply run <code>git commit --no-verify</code>.

=== Applying The Format Changes ===

Once you know which files are improperly formatted, and what changes need to be made to fix them, you have two options. The first option is to manually apply the required changes to your code, and submit them as a new commit. Alternatively, you can run the below command, replacing <code>FILE...</code> with the paths to the files that need to be fixed.

<pre>
~/.../pioneer $ clang-format -style=file -i FILE...
</pre>

This will direct clang-format to overwrite your code with the properly formatted version. It is recommended that you do not do this blindly, but rather determine which changes will be made first (by running <code>git commit</code> or <code>scripts/pre-commit-hook.sh</code> to trigger the validation hook).

A script to automatically apply the results of the clang-format validation pass is planned, but not currently written. Once it is created, applying the code format changes will be as simple as running a single script from the main pioneer directory, and confirming the changes you want to apply.

User:Sturnclaw

2018-10-20T18:21:29Z

Sturnclaw: Add reference links for the rendering engine.

User:Sturnclaw

2018-10-20T17:17:32Z

Sturnclaw: Add some info to the rendering section

Roadmap

2018-10-20T16:53:43Z

Sturnclaw: Link The List into the roadmap.

Please note: this page is old, not updated, and should be more thought of as a general outline of the direction we want to take the game in.

An annotated and updated (but incomplete) fork of the roadmap may be found at [[User:Sturnclaw|Sturnclaw's List]].

== First milestone ==

Basically we want external interfaces to be stable.

*New save file format (Done?)
*Separate Player from Ship (breaks Lua)
*Turn Missiles into guided Projectiles
*Module manifest
*[https://github.com/pioneerspacesim/pioneer/issues/4078 Convert to dear-imgui] (In progress)
*Starsystem generation rewrite (plus custom systems)
*3D cockpits (only visual, not functional) (In progress)

== Second milestone ==

*Gameplay stuff, redesigned UI. Dunno yet.
*Functional 3D cockpits

 

== Older stuff ==

Pioneer has changed versioning system and will no longer release a 1.0 version. Development will continue continuously with new features and fixes added, making every new version slightly better than the one before. Below is a compiled list of features.

'''''Warning:''' This list is incomplete - and under active discussion so subject to change''

 

=== UI features ===

*Star views and navigation
**Combine system (orbit) view into star map
**Bookmarks, travel log
**Maybe other streamlining as well? such as?
**is galaxy view useful at all?

*Missions and station interface
**Redesign the bulletin board to allow filtering and searching (e.g., adverts have tags, as shown in [http://i.imgur.com/HJH9L.png this old mock-up]).
**Better access to missions or BB. maybe alerts?
**Centralise bulletin board within the station interface (ie, everything else hangs off the bulletin board; the BB is basically the station-wide-web)
***Replace the "standard" commodity market with multiple traders/shops advertising on the BB
***Replace the "standard" ship equipment and servicing screens with mechanics advertising on the BB
***Replace the "standard" ship purchase screen with specialist shops advertising on the BB, plus also individual pilots posting ship-for-sale and ship-wanted adverts

*Rewrite? the [https://pioneerspacesim.net/forum/viewtopic.php?f=3&t=24 HUD]
*[https://github.com/pioneerspacesim/pioneer/issues/58 Add chase camera], padlock

=== Technical features ===

*[[Commodity_Prices|Commodity Prices]] (see link for more) / Economy will be more advanced (Dynamic?)
*Weapons
**goals: allow more than just laser bolts (beams, missiles), auto-tracking guns and [https://github.com/pioneerspacesim/pioneer/pull/2844 turrets]
**rewrite, basically
**conflicts with lua trade goods/equipment?

*Factions
**Remove random generation of factions
**Factions into translation system
**Custom systems into translation system
*Separate Player from Ships
**to enable shuttlecraft and remote drones
*Hitpoints: use generic HP value instead of mass. system specific damage?
*Cargo: use kg instead of tons
*AI
**needs more higher level stuff like basic self preservation, modules must not have to implement their own (like tradeships...)
**formations, anyone?
**AI vs AI?

=== Gameplay features ===

*Military progression / treason.
*Something like the Scout missions the walterar has done, exploration jobs.
*No hypersace from in atmosphere / or too close to a planet surface.
*In-system hyperspace jumps to make assassination missions and piracy actually possible.
*Alternatively a Fast-As-Light drive, Shadmar has taken a hacked one I (fluffyfreak) wrote and updated it for Paragon.
*A reason to actually have [[Crew|Crew]] on the ship.
** better hyperjump planning, for multiple jumps,
** Better autopilot (i.e. make actual auto equipment perform worse)
*Cargo has volume, and this is what limits a cargo hold. [http://pioneerspacesim.net/forum/viewtopic.php?f=3&t=245 forum]
*Allow player to buy some types of ship equipment as cargo and have it fitted elsewhere
*Ship visual customization
*Space stations
**external docking
**traffic rules (don't allow modules to let ships idle forever)
*Ship to ship [https://github.com/pioneerspacesim/pioneer/issues/3071 docking] / [https://github.com/pioneerspacesim/pioneer/issues/3070 comunication]
*Networking / "Fake multiplayer" [[Network_features|Network features]]

User:Sturnclaw

2018-10-18T21:11:24Z

Sturnclaw: Add section on Lua.

Engine Overview

2018-10-18T19:13:55Z

Sturnclaw: Add section on Lua.

This page details the inner workings of the game's engine, and various high-level looks at the gameplay systems.

== Rendering ==

For information about the game's rendering system, see [https://pioneerspacesim.net/forum/viewtopic.php?f=3&t=489 Fluffyfreak's post].

== Input ==

[[File:Input_system.svg|thumb|The engine's input system, as seen from application code.]]

TODO: details on input, including binding axes / actions, reading input, and how to add a new input method

 

== Lua Engine ==

TODO: describe the state of the lua runtime, including sandboxing, core imports, and binding ''your'' code to Lua.

== Models and Textures ==

TODO: merge the engine-specific parts of the wiki here, provide a technical overview of the scenegraph system.

== Ships ==

[[File:Ship_systems.svg|thumb|A ship, as represented in code.]]

TODO: information about how a ship (should) work, describe the damage model, the equipment model, the hardpoint system, etc.

Engine Overview

2018-10-18T19:12:13Z

Sturnclaw: First stab at engine internals documentation.

This page details the inner workings of the game's engine, and various high-level looks at the gameplay systems.

== Rendering ==

For information about the game's rendering system, see [https://pioneerspacesim.net/forum/viewtopic.php?f=3&t=489 Fluffyfreak's post].

== Input ==

[[File:Input_system.svg|thumb|The engine's input system, as seen from application code.]]

TODO: details on input, including binding axes / actions, reading input, and how to add a new input method

 

== Models and Textures ==

TODO: merge the engine-specific parts of the wiki here, provide a technical overview of the scenegraph system.

== Ships ==

[[File:Ship_systems.svg|thumb|A ship, as represented in code.]]

TODO: information about how a ship (should) work, describe the damage model, the equipment model, the hardpoint system, etc.

File:Ship systems.svg

2018-10-18T19:08:37Z

Sturnclaw: A high-level overview of the ship code in pioneer.

== Summary ==
A high-level overview of the ship code in pioneer.

File:Input system.svg

2018-10-18T18:59:39Z

Sturnclaw: A graph of the input subsystem.

== Summary ==
A graph of the input subsystem.

Pioneer Wiki

2018-10-18T18:55:59Z

Sturnclaw: Add a new link to the documentation page for the engine's internals

Pioneer is a space adventure game set in the Milkyway galaxy at the turn of the 31st century. The game is open-ended, and you are free to explore the millions of star systems in the game. You can land on planets, slingshot past gas giants, and burn yourself to a crisp flying between binary star systems.

If you are new to pioneer you may want to know [[How_to_start|how to start]].

*[http://pioneerspacesim.net/download Download Pioneer] for Windows, Linux and Mac OSX

Please make this wiki nice. Add stuff about mods, dev, whatever. Be awesome! [[Getting_started|How to get started]].

----

{| width="100%"
|-
| style="background:#bbffbb; border:2px solid #99ee99; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Community ===

*[http://pioneerspacesim.net/ Pioneer Space Sim Homepage]
*[http://spacesimcentral.com/ssc/forum/23-pioneer/ Community forum]
*[http://pioneerspacesim.net/forum Developer forum]
*[http://webchat.freenode.net/?channels=#pioneer Pioneer Space Sim on IRC]
*[http://pioneerspacesim.net/+ Pioneer Space Sim] on Google+
*[http://twitter.com/pioneerspacesim @pioneerspacesim] on Twitter

----

*[[Manual|Basic Manual]]
*[[Flight_UI|Flight UI]]
*[[Keyboard_and_mouse_controls|Keyboard and mouse controls]]
*[[Tutorials|Tutorials]] (Outdated and WIP)
*[[Mission_Types_and_BBS|Mission Types and BBS]]
*[[Settings_Menu|Settings Menu]]
*[[FAQ|FAQ]]
*[[Media_Coverage|Media Coverage]]

| style="background:#fff9b1; border:2px solid #f0fe66; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== The Pioneer Universe ===

*[[Pioneer_Universe|Pioneer Universe]]
*[http://pioneerwiki.com/wiki/Category:Ships Ships] (work in progress)
*[http://pioneerwiki.com/wiki/Category:Manufacturers Manufacturers] (work in progress)
*[[Places_of_interest|Places of interest]]
*[[Ship_Equipment|Ship Equipment]] (work in progress)

|}

 

{| width="100%"
|-
| style="background:#f0f0ff; border:2px solid #c6c9ff; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Content Creation ===

*[[Mods|Mods]]
*[[Scripting_and_Mission_Creation|Scripting and Mission Creation]]
*[[Custom_Systems|Custom Systems]]
*[[Design_and_Concept_art|Design and Concept art]]
*[[Modeling,_Texturing,_Graphics_Design|Modeling, Texturing, Graphics Design]]
*[[Music_and_Sound|Music and Sound]]
*[[Translations|Translations]]
*[[Licensing|Licensing]]

| style="background:#fff3e3; border:2px solid #ffc9c9; padding:2px 2px 4px 4px; vertical-align: top" width="33%" |
=== Development ===

*[[Design_Scope|Game Scope]]
*[[How_you_can_contribute|How you can contribute]]
*[[Getting_Started_with_Development|Getting Started with Development]]
**[[How_to_communicate|How to communicate]]
**[[Using_git_and_GitHub|Using git and GitHub]]
**[[Code_style|Code style]]
**[[Development_team|Development team]]
**[[Engine_Overview|Engine internals overview]]
*[[Development_Model|Development Model]]
*[[Design_Workflow|Design and Project Management Workflow]]
*[https://github.com/pioneerspacesim/pioneer/issues Issue tracker]
*[[Roadmap|Roadmap]]

|}

Pioneer is brought to you by a flock of [https://github.com/pioneerspacesim/pioneer/blob/master/AUTHORS.txt opensource beardy-weirdies], and is [http://www.gnu.org/licenses/gpl.html Free Software]

'''__NOTOC__'''

User:Sturnclaw

2018-10-16T20:41:18Z

Sturnclaw: Add the ECS and Input tasks

User:Sturnclaw

2018-10-16T18:01:29Z

Sturnclaw: Start scaffolding The List.