Programming Work

From FreeOrionWiki

A list of things that must, should or could be done by programmers.
Please, only programmers change this!

Ask Geoff the Medio if you'd like to help, or need help, with a programming task on this page.

Contents 1 Binaries 2 Misc 3 Player order-giving improvements 4 UI improvements 4.1 Production screen 4.2 Research screen 4.3 The SidePanel 4.4 Galaxy map screen 4.5 Fleets Windows 4.6 Design Window 5 New Effects 6 New Conditions 7 Referenceable Object Properties

[edit] Binaries

• Provide compiled binary downloads for operating systems other than WinXP / Vista. Non-Intel Mac OSX binaries, and Linux-flavour-specific packages would be appreciated.

[edit] Misc

• Keep an eye on SourceForge bug reports and fix non-minor ones.

• Implement SourceForge feature requests (typically requires design discussion on forums)

• Write up and maintain compilation User's Stories.

• Keep MSVC and XCode project files and SCons build files updated (if anyone adds or removes source files)

• Make planet appearance on the sidepanel vary depending on its in-game state, including presense of specials (including a Gaia special) or industry meter level. Planets should also have separate night-side textures (lights in dark), and be able to have ring systems surrounding them (mutually shadowing with planet), and battle damage (if not treated as a special). There are currently hard-coded adjustments to rotation speed or axial tilt, but these would be better treated as scriptable properties of the specials themselves. A future-proof / extendible format to specify this sort of change, or other appearance alterations of in-game objects due to specials (or other similar content types) would be useful. Note that this is probably not suitable for a first-time contributor, as it likely requires significant artist interaction and understanding of how FreeOrion planets, effects, techs, and other content work, both conceptually and in-code.

• Overhaul the non-graphical combat system. Even after 3D combat is fully functional, some battles will need to be resolved automatically, without player input or display. AI vs AI battles that a player doesn't want to observe, or player-vs-AI or player-vs-player battles may be auto-resolved to save time in games, particularly multiplayer. The automatic combat system should resolve battles fairly and quickly, and take into account as much tactical information about the relevant combat forces in a system where a battle is occuring. There has been no offical design work on how automatic combat resolution should work, so feel free to make whatever choices you feel are appropriate in designing this system. Making things easily configurable so that later balancing changes can be made simply would be best.
  • One possiblity to consider is making the automatic combat system a Python script. The server would expose an interface to Python that indicates the initial combat force at the start of the battle, and would call a ResolveCombat function in Python. The Python script would decide what happens to the various initial forces during combat, and call back to the interface to specify the results of combat.
• Currently all keyboard bindings in-game are hard-coded. It would be much nicer to have a GUI or configuration file-based method to reassign keys. Likely key bindings could be stored in config.xml the same way other information is stored in it. Entries in config.xml can be added by adding a function like void AddOptions(OptionsDB& db) in the anonymous namespace in ClientUI.cpp or MapWnd.cpp in files that don't already have one, or adding entries to an existing function of that sort in the file where a stored windows position needs to be retreived. There should be a new option for each action a keypress can take, and the stored value would be some representation of the keypress or keypress and modifier key (eg. shift, ctrl, etc.). MapWnd::ConnectKeyboardAcceleratorSignals and MapWnd::SetAccelerators need to be modified to get the keys to bind to various commands from the options DB using the standard GetOptionsDB().Get<TYPE>("option-name-text") lookup. It might be possible to make the option TYPE std::pair<GG::Key, GG::Flags<GG::ModKey> > to store the key + modifier combination, but I don't know if this will automatically convert to text, and if so, if the conversion is easily editable. If not, a bit of custom code to convert to and from a string representation would be needed.

• Change victory conditions so that players can continue in the same galaxy after defeating all other empires PARTLY DONE IN SVN, should they be so inclined. Optionally, add multiple victory conditions and a way to choose between them during galaxy setup. Perhaps start or continue a forum discussion about what victory conditions there should be.

• Implement full-fledged visibility system. On the galaxy map, what is/isn't visible is poorly designed at best. Visibility tests, done on the server, need to be implemented to determine which UniverseObjects each client should receive updates about. Previously-known states of UniverseObjects that a client can't see this turn should probably be retained as well, while accounting for objects that have been destroyed but which a particular client might not know are destroyed. Note how destroyed objects are currently tracked when a client does observe the destruction. Implementation should conform to the relevant section of the v0.4 design document with respect to visibility tests with stealth and and detection meters and distance dependence.

• Shaders, shaders, shaders. The ogre-integration branch needs love. Competent GLSL programmers are welcome to write swanky visuals and effects via shaders.

• Visual effects. If you have some interesting particle, shader-based, or GL fixed-functionality special effects, such as for explosions, or shield effects, or ray guns up your sleeve, please contact Tzlaine.

• A full-featured and easy-to-use GUI editor would be invaluable to designers, artists, and coders. A GUI editor would really speed up development for all three groups. GG has an attempt at one, but it's flaky.

• Write initial Python AI. Note that most or all of the high-level game design is in flux as we add features. The lower-level stuff (like how to move around and select targets in the combat system) may be possible to write once and for all right now. It would be good if the AI could be updated to build ships and buildings and research techs.

• Improve and extend the functions and data exposed to Python for AI.

• Design and implement FreeOrion galaxy map saving and loading routines. It should be possible to load a map when starting a new game, instead of randomly generating one, and to save maps from the GUI or extract them from FreeOrion saved games. Maps should store stars, planets and planet specials. When loading, it should be possible to use only the stars (and randomly populate the systems), or use only stars and planets (and randomly add specials), or use all of the data.
  • A way to do this might be to use a SVG image to store map data. Positions of stars would be indicated by circles in the image, and star colour would be indicated by the colour of the circle. Starlanes between systems could be indicated by lines between the system circles. Planets could be indicated by circles within the system circles, and planet type would be indicated by colour as well. Names of systems and planets could be text within their respective circles. Specials on objects could be indicated by boxes within the circle of a planet or system that contain the text that indicates the name of the special. Buildings on planets could be indicated by a different colour box that contains the name of the building. A zoomed-out (to see the whole universe) rendering of this SVG would resemble the in-game map, and zooming in would reveal details of the contents of systems and objects in systems or on planets in systems.

• Create a FreeOrion scenario and / or map editor. This can probably be done as a modification of the in-game GUI, so the standard MapWnd, SidePanel, etc. could be modified to add this functionality when the client is in editor mode. Should be possible to load maps and saved game, and save maps and saved games from in the GUI.

• Expose a Python scripting interface for server-side universe creation and game start setup scripts. The starting unlocked items, ship designs and starting fleets are currently defined in content files in the default directory, but the addition of a shipyard and palace and the homeworld special to the homeworld are hard-coded in C++ during empire generation. It would be better if they were scripted and adjustable. There is also currently no way to significantly alter the game start conditions... Useful things might be to mark other systems as explored, give different types or numbers of planets to empires. Even more significantly, the placement of systems and planets and starlanes should be fully scriptable. The existing C++ universe generation functions can be exposed to and called from python to provide a way to replicate the existing functionality, but it should be possible to implement new generation routines in Python that just call an exposed C++ function to add a system, planet, starlane, special or building. Placement of empires and their homeworlds should also be scriptable in the same way.

• Write code to get GG::Clr defined in a text file to determine the colours of meters in the GUI. The function GG::Clr MeterColor(MeterType meter_type) in InfoPanels.cpp should be updated to use this instead of hard-coded meter colours. Code to read colours already exists and is used for parsing tech category definitions in techs.txt, so doing the same for meters should be relatively simple.

[edit] Player order-giving improvements

• Make it possible to queue, edit, delete (etc.) fleet move orders
  • I think editing and deleting are of questionable utility. I think queueing and clearing are sufficient. -- Zach
  • An ideal interface for move order editing would be something like Google maps directions that allows one to drag waypoints from a long a route to another location. to have that location inserted into the route.
  • More important is appending destinations to the end of a move order sequence. Perhaps shift- or ctrl-clicking on a system would append that system to the end of the destination queue?
• Also allow other fleet actions to be queued, like colonizing a planet
• Make it possible to give multi-part orders, like colonizing a particular system or planet that a fleet is not located at, or making rally points for new ships away from where they are built
• Add some player-helping AI scripts so the player can order a fleet to "explore"
• The ExecuteImpl functions of the various Order subclasses in Order.cpp should validate the orders they're about to execute, to ensure that invalid orders can't be sent by players using modified clients or improperly written AIs. For example, in FleetMoveOrder, a player could write a custom client that sends a FleetMoveOrder with a move route that doesn't follow the rules about where players can send ships. A bit of validity checking has been added to that function, but it should also check the route so that when the order is executed on the server, there's no way for an invalid order to be accepted. This validate should ensure that the series of systems in the order's route are all connected by starlanes known to the player that owns the fleet that issued the order. Other Order subclasses likely have similar checks that could be added as well.

[edit] UI improvements

• Various feature requests on sourceforge are worth implementing.

• Ship design descriptions, as seen in the encyclopedia panel when clicking on the ship design in the list on the production screen, or on the list of designs on the design screen, shows a few statistics about the design such as attack, defense and speed. This should be extended to show a few other statistics, like the max health, fuel capacity, stealth, detection, and shields, all of which are meters. This will require adjusting the ship design case code in EncyclopediaDetailPanel::Reset() to pass a few more values to be inserted into the description. The description string itself can be found in that function, and needs to be expanded in eng_stringtable.txt to accept more parameters and display them appropriately. The way to do this should be apparent from the existing examples in that stringtable entry and code.

• The function RomanNumber in MultiplayerCommon.cpp should be updated to return the proper roman numerals for values above 1000. Unicode character encodings can be written into text similar to "\xC2\xB5" for μ in UTF-8.

• The function DoubleToString in ClientUI.cpp is used to do custom conversion of double values into strings for display to the user, with a controlled number of digits displayed. There are some issues with it:
  • Currently it displays the result with a SI unit prefix chosen based on the absolute value of the number, which may include prefixes like m (milli) or u (mu for micro) for values with magnitude much less than 1. For most values displayed the the player, it would be preferable to not use micro or milli prefixes, and instead display a decimal with leading zeros, such as 0.014 instead of 14 m. The user likely won't care about such small amounts of production, and we will probably want to effectively round such values to 0 in many cases. To allow this, the DoubleToString function should be modified to not show, or to have an option not to show, any values formatted with prefixes below ones (eg. not use milli, micro, nano, etc. prefixes).
    • The results can be tested by starting a new game, colonizing a new planet, and changing its secondary focus to balanced. The research, industry, minerals and trade output indicators should show a value around 100m now, or 0.10 after this modification is done.
  • Currently, production amounts over 1000 are shown with the k prefix (SI for kilo = thousand). This is fine, and should be kept (unlike removing m or mu) but there is a problem with the number of digits shown. Presently, if the amount of resource is 8422 then the string produced is 8k even if the number of digits requested was 3. It should be 8.42k.
    • Testing this could be done by starting a game and accumulating a lot of stockpiled food by setting the homeworld to double food focus, and ending turn many time to accumulate food. Other resources could also be accumulated, and might go faster, since minerals or trade are stockpiled, but aren't consumed if not building anything (minerals) or at all (trade).
  • These issues should be relatively self-contained and easy for someone new to FreeOrion to work on, as they don't depend on anything but the inputs to the DoubleToString function.

• Create an encyclopedia index of clickable text that opens an EncyclopediaDetailPanel to show the appropriate info. Ideally the list would be categorized, perhaps with filters like for tech categories on the research screen or part types on the design screen. This list could be shown in the encyclopedia detail panel (where info about techs, ship parts, hulls, ship designs, building types are shown on their respective screens when those items are selected) and let the user click on an item to see its detail by adding linktext (as for help on the forums if you need to know how to add links to text).
  • There could be an "show index" button on the encyclopediapanel to bring up a list of topics
  • There could also be forward, back and up buttons on the panel, to navigate between the index, a list of all topics in a category, and individual info pages. Forward and back buttons would require the encyclpedia panel to have some memory of previously shown pages, which would need to be added.

• Investigate making dragging items on queues (production, research) determine where to drop something based on something other than the mouse cursor position. When dragging a box like a tech or production item panel around the queues, it's strange to have the apparent position of the box be different from the active position determined by the mouse cursor position. This means that if the box is dragged from the top, it will appear lower than it would if it was dragged from the top, for a given "active" position. (Where the "active" position is the mouse cursor position which is actually used to determine where in the queue the box it dropped). Ideally the centre point of the box would be used to determine where a box will be dropped, regardless of where on the box the cursor was when dragging started.

[edit] Production screen

• Make the buildable items list sortable, with resizable columns
• When a building is selected in the buildable items list, get the building's effects groups and find all objects that would be targets of the building's effects if built at the selected location. Mark these objects in the UI somehow (discuss with graphics team).
• Add lines in the top-left production summary for the currently selected system. Now the total empire PP and wasted PP are shown, but it would be good to also show the available and wasted PP in the selected system.
• Add "At PlanetName" to queue items where PlanetName is the name of the build location for the queue element (which is probably a planet, but don't assume that). This is a very important and hopefully easy addition that would make understanding the queue much easier when there are items being built at many different systems.
• Make dragging a building from the buildable items list onto a planet attempt to order that building to be produced at the planet. Add the building to the end of the queue. Do the same for ships.
• Make dragging a building or ship onto the production queue enqueue that building or ship at the selected planet. If no valid build location for the dragged item is selected, then do nothing.
• Make dragging an item from the queue onto the empty space of the galaxy map, or onto the buildable items list, remove the item from the queue.

[edit] Research screen

• Add a sortable list of techs as an alternative to the tech tree view - Partly done, but list view should be put in a resizable window and made sortable
• Make techs on tree look a bit more like popup tooltips (discuss on forum first)
• Change how the tree panel layout is done.
  • It shouldn't be necessary to redo the graph layout when zooming. Recalculating this for each zoom makes zooming feel clunky and slow.
  • Get GraphViz to arrange the techs hoizontally according to some controllable logical positioning. The placement of tech panels presently seems to have no useful reasoning behind it.
  • Replace GraphViz with custom graph layout code you write yourself or find from suitably-licensed open-source projects. There have been various version issues and (resolved) license issues with GraphViz
• Make layout changes persist between executions of the program. The user / player can rearrange and resize several windows on the tech screen, however these changes are lost when the user exits FreeOrion. The positions of the various windows could be stored in config.xml (similar to how galaxy setup selections are stored) and retreived the next time the program is run. Positions should probably be stored in a resolution-independent way, so that changing the resolution doesn't cause windows to disappear off screen, and/or sanity checks for size and position should be done when doing initial layout / retreiving from the options DB to ensure a reasonable layout. Entries in config.xml can be added by adding a function like void AddOptions(OptionsDB& db) in the anonymous namespace in ClientUI.cpp or MapWnd.cpp in files that don't already have one, or adding entries to an existing function of that sort in the file where a stored windows position needs to be retreived. The new options should store the x and y positions and height and width of the windows to have persistent locations between executions. The constructors for those windows could be passed (or modified to take) the positions and sizes as parameters, or the code that creates the new windows could reposition them, or an existing function to position windows could be altered to use them. Entries for these options aren't really needed in the Options screen.

[edit] The SidePanel

• Fix up the top portion with the system resource summary, system droplist and star graphic
• Design and add a "shipyard in system" box to the system info section
  • Show ships being built, similar to buildings being built on planet panels
• Make it possible to change the width of the sidepanel
• Make it possible to toggle between opengl-rendered planets and static planet images (available in the art directory). There should be a toggle / setting in the UI options menu tab for this.
• Add a way to order the desctruction of buildings. The obvious place for this is on the sidepanel, perhaps by right clicking to show a popup option to destroy it, or double-clicking on a building icon. Doing this should mark the building with a big X to indicate it will be destroyed during the next turn processing. Double-clicking or right-click-popup-optiong-selecting again should cancel the destruction.

[edit] Galaxy map screen

• Add tooltip to the empire resource summaries at the top of the map screen. This should list, with text explanation, the stockpile, income, expenditures, and net change.
• On empire resource summary, list all + and - contributions to the production and consumption of each resource. Something like " ObjectType ObjectName +/- ### " in a column.
• Making zooming in / out with the mouse scrollwheel do the zooming centred on the cursor position, rather than the centre of the screen.
• In MapWnd::RenderFleetMovementLines the RATE constant determines how fast the dots move along the path fleets will move in future turns. This RATE could be made user-configurable, just like the MOVE_LINE_DOT_SPACING constant, with an entry in the OptionsWnd with which to set it. This should be straightforward, other than needing to figure out where to add the option database entry (in AddOptions) and where to add the GUI widget to set the option (in OptionsWnd::Init). Entries also need to be added to the stringtable, all analagous to what's done for the MOVE_LINE_DOT_SPACING option.
• In MapWnd::RenderFleetMovementLines, move_line_animation_shift (a file-level static variable) is set each frame. It's then used in RenderMovementLine to determine where to position the first fleet move line dot after the start of the first segment of the move line. If several empires' fleets are all leaving the same system along the same starlane, these dots will overlap, and only one will be visisble. It would be better if there was an empire-id-dependent additional offset for the dot positions, so that multiple empires' dots can be seen moving along the same starlane.

[edit] Fleets Windows

• Add a speed indicator to fleet and ship panels in the lists of fleets and ships. A single ship's speed should be gotten from the ship's ShipDesign which contains a HullType which has a member StarlaneSpeed() which returns how fast a ship moves along starlanes. The speed of a fleet should be the least of the speeds of the ships it contains, which should be calculated similarly to the fleet's fuel statistic, except that StarlaneSpeed isn't a meter. A statistic icon to indicate speed should probably be added to both fleet and ship panels, similarly to how the current ones are added.

• Figure out a good way to move up and down the partition between the top third of the panel that shows fleets and the bottom panel that shows ships within the selected fleet. Some way to drag a partition would be appropriate. This needs to work whether or not there is a new fleet drop target in between the two.

• Presently, the "active" FleetWnd is the one representing the last-clicked fleetbutton, or the one last clicked on by the player, or in which a fleet was clicked. This is only relevant when there are multiple fleet wnds on screen, which can be enabled in the options menu. The active fleet wnd can be determined by seeing which fleet button has white (for selected fleet) move line dots coming out of it on thoe map. It should be possible to set the selected fleetwnd by clicking on just about anything in it. This should include changing ship selection in fleet info section of the fleetwnd (at the bottom). Making this happen would require getting some signals of selection changes or clicks on the relevant list box, and propegating these as is done for the fleets list box at the top of the fleetwnd. This shouldn't be too complicated to figure out.
  • It might also be nice to indicate somehow which FleetWnd is selected.
• Create a full-screen fleets summary view
  • List all fleets, friendly and enemy
  • Expandable to show ships in fleet
  • Show destination, location, other stats and info
  • Sortable
  • This could be part of a list to show *everything* in the universe... sorted by owner, type (fleet, ships, planets, systems), or other properties.

[edit] Design Window

• DesignWnd::MainPanel::AddPart in DesignWnd.cpp could be improved. This function should "intelligently" find a slot in which to place the passed part, moving around other parts within the design if necessary. Currently it just tries to find an empty slot that can accept the part, and makes no effort to adjust things to accomodate a new part if only possible nontrivially.

• Add DesignWnd::MainPanel::CanBeAddedToHull that returns true if a passed PartType can be added to the current in-progress ship design without any other modifications. That is, return true if MainPanel::AddPart would be able to add the part, and false otherwise. This will be used to grey out / disable parts that can't be added to the current design, due to being unable to fit in any slots, or any unfilled slots.

• Add tooltips to SlotControls. PartControls (in the parts list, or after being dropped into a SlotControl) have tooltips indicating what kind of part they are. Empty SlotControls (in the middle panel where parts can be dropped after selecting a hull) could also have a tooltip indicating what kind of slot they are. This should be fairly simple to do by copying what's done for PartControls. Make sure that SlotControl tooltips are replaced by PartControl tooltips when a PartControl is dropped into a SlotControl, though, or modify the PartControl tooltip when it is in a SlotControl, to indicate what kind of slot the part is in (this would be preferred).

• Make the parts list accept drag-drops of PartControls. If a PartControl is dragged from the parts list to itself, do nothing. If the PartControl is dragged from a SlotControl in the main design panel, then remove the part from the slot.

• Add a way to delete existing ship designs that the player no longer wants. Should remove the shipdesign from the player's list of designs, but the design itself needs to be kept in the universe's record of them, as ships may exist that use the design. It may be preferable to "obsolete" designs rather than delete them from an empire, however, as espionage might be able to steal ship designs, and if players can create and delete designs during a turn, they could create a design, build ships, then delete the design to prevent it from being stolen by espionage. This sounds fine, but would create the need for annoying design micromanagement and recreation to avoid that espionage, which would be annoying. If instead designs are obsoleted but still kept around, it gives players a way to remove the old designs from their production lists without affecting espionage.

[edit] New Effects

• Generate SitRep messages. SitReps in the game now are generated from C++ code. Any changes due to effects on techs, buildings, specials or other content defined in text files doesn't have a SitRep generated for it. If there was a SitRep generating effect, it could be used to notify players when an effect does something.
• Set research progress for a tech for an empire
• Implement CreateBuilding::Execute in Effect.cpp. This function should do the work of executing the CreateBuilding effect. This can be modeled after the CreatePlanet effect which is defined nearby in the same file. Created buildings should be owned by the owner(s) of the planet on which they are created, which may be no owners if no player owns the target planet. This should be a fairly short addition, but might require a some investigation or understanding of the existing codebase to do successfully. Make sure newly-created buildings on planets owned by players or owned by no-one don't crash the client. Make a special that creates a building and then removes itself on the first turn to test the effect; this can be used to create buildings throughout the universe at the start of the game, on planets for players to colonize and then make use of.
• CreateSystem - similar to CreatePlanet and CreateBuilding, but for systems. Should not allow creating systems at the location of another system. Would be nice if creating a system at the location of a ship that's travelling on a starlane would cut the starlane, perhaps connecting two new starlanes between the new system and the ends of old starlane.
• AddStarlane / RemoveStarlane - Between the target object and objects matching a condition parameter (like the MoveTo effect's condition parameter)
• SetRotationSpeed / SetAxialTilt - A few specials (Slow Rotation, Tidal Lock, High Axial Tilt, Gaia) should modify their planet's appearance. Currently the rotation and tilt specials are checked for during universe generation, and any planets with them have their rotation or tilt modified. It would be better if the specials could do this with an effect themselves, so that we can remove the hard-coded special names from the c++ code, and could add these specials later in the game and have their effects be visible.
• SetTexture - Specials could set the texture used to render a planet, allowing specials to drastically change a planet's appearance. A likely use is to make Gaia planets look different. Could be later extended to other objects, as appropriate and as needed.

[edit] New Conditions

• Sorted - takes an object property, like Target.MaxFarming, and a number of objects, like 3, and matches that number of objects that have the largest or smallest value of the property
• Targetted - assuming there is some UI mechansim to target an object with another object, probably involving issuing an order to do this targetting, there should be a Targetted condition which matches objects targetted by the source object
• Age / CreationTurn - matches objects that are within the specified range of number of turns since they were created, or matches a range of creation turns
• PlanetSlot - which slot a planet or other object is located in, in its system
• Speed - distance per turn an object is currently moving (and perhaps also max speed?). Most applicable to fleets and ships travelling between systems.
• Moving / Stationary - whether a ship or fleet (or other object?) is moving at all (presumably under its own power) on a given turn. Unnecessary if a speed condition is available.
• ShipDesign id - similar to Building name, matches ships with a particular design. Ship designs are created in-game by players, while building names are defined in contenxt text files, so it will be necessary to be able to reference Source.DesignID or similar for this condition to be useful.
• Other ShipDesign details: designing empire, designed on turn / age of design, hull type or parts

[edit] Referenceable Object Properties

For effects and condition definitions:

• SourceTargetDistance - direct line distance between source and target being acted on
• SourceTargetJumps - number of starlane jumps between source and target being acted on, using starlanes known of by source's empire
• PlanetSlot - which slot a planet or other object is located in, in its system
• Speed - distance per turn an object is currently moving.
• Design and DesignID of a ship
  • Cost
  • Minimum build time
• BuildingType of a building
  • Maintenance cost