1
0
mirror of https://github.com/zenorogue/hyperrogue.git synced 2024-10-31 19:36:16 +00:00

Doxygen files added

This commit is contained in:
Zeno Rogue 2019-09-12 23:35:04 +02:00
parent ec5b16691e
commit 8a8f25ee11
2 changed files with 471 additions and 0 deletions

283
Doxyfile Normal file
View File

@ -0,0 +1,283 @@
DOXYFILE_ENCODING = UTF-8
PROJECT_NAME = "HyperRogue"
PROJECT_NUMBER = 11.2
PROJECT_BRIEF = "game/visualization engine based on non-Euclidean geometry"
PROJECT_LOGO = hr-icon-png96.png
OUTPUT_DIRECTORY = doc
CREATE_SUBDIRS = NO
ALLOW_UNICODE_NAMES = NO
OUTPUT_LANGUAGE = English
OUTPUT_TEXT_DIRECTION = None
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ABBREVIATE_BRIEF = "The $name class" \
"The $name widget" \
"The $name file" \
is \
provides \
specifies \
contains \
represents \
a \
an \
the
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = YES
STRIP_FROM_PATH =
STRIP_FROM_INC_PATH =
SHORT_NAMES = NO
JAVADOC_AUTOBRIEF = NO
QT_AUTOBRIEF = NO
MULTILINE_CPP_IS_BRIEF = NO
INHERIT_DOCS = YES
SEPARATE_MEMBER_PAGES = NO
TAB_SIZE = 4
ALIASES =
TCL_SUBST =
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
OPTIMIZE_OUTPUT_SLICE = NO
EXTENSION_MAPPING =
MARKDOWN_SUPPORT = YES
TOC_INCLUDE_HEADINGS = 0
AUTOLINK_SUPPORT = YES
BUILTIN_STL_SUPPORT = NO
CPP_CLI_SUPPORT = NO
SIP_SUPPORT = NO
IDL_PROPERTY_SUPPORT = YES
DISTRIBUTE_GROUP_DOC = NO
GROUP_NESTED_COMPOUNDS = NO
SUBGROUPING = YES
INLINE_GROUPED_CLASSES = NO
INLINE_SIMPLE_STRUCTS = NO
TYPEDEF_HIDES_STRUCT = NO
LOOKUP_CACHE_SIZE = 0
EXTRACT_ALL = NO
EXTRACT_PRIVATE = NO
EXTRACT_PACKAGE = NO
EXTRACT_STATIC = NO
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_LOCAL_METHODS = NO
EXTRACT_ANON_NSPACES = NO
HIDE_UNDOC_MEMBERS = NO
HIDE_UNDOC_CLASSES = NO
HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = NO
INTERNAL_DOCS = NO
CASE_SENSE_NAMES = YES
HIDE_SCOPE_NAMES = NO
HIDE_COMPOUND_REFERENCE= NO
SHOW_INCLUDE_FILES = YES
SHOW_GROUPED_MEMB_INC = NO
FORCE_LOCAL_INCLUDES = NO
INLINE_INFO = YES
SORT_MEMBER_DOCS = NO
SORT_BRIEF_DOCS = NO
SORT_MEMBERS_CTORS_1ST = NO
SORT_GROUP_NAMES = NO
SORT_BY_SCOPE_NAME = NO
STRICT_PROTO_MATCHING = NO
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
SHOW_USED_FILES = YES
SHOW_FILES = YES
SHOW_NAMESPACES = YES
FILE_VERSION_FILTER =
LAYOUT_FILE =
CITE_BIB_FILES =
QUIET = NO
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = NO
WARN_AS_ERROR = NO
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
INPUT =
USE_MDFILE_AS_MAINPAGE = source-doc.md
INPUT_ENCODING = UTF-8
FILE_PATTERNS = *.cpp hyper.h classes.h sysconfig.h source-doc.md
RECURSIVE = NO
EXCLUDE =
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
EXCLUDE_SYMBOLS =
EXAMPLE_PATH =
EXAMPLE_PATTERNS = *
EXAMPLE_RECURSIVE = NO
IMAGE_PATH =
INPUT_FILTER =
FILTER_PATTERNS =
FILTER_SOURCE_FILES = NO
FILTER_SOURCE_PATTERNS =
USE_MDFILE_AS_MAINPAGE =
SOURCE_BROWSER = NO
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
REFERENCED_BY_RELATION = NO
REFERENCES_RELATION = NO
REFERENCES_LINK_SOURCE = YES
SOURCE_TOOLTIPS = YES
USE_HTAGS = NO
VERBATIM_HEADERS = NO
ALPHABETICAL_INDEX = YES
COLS_IN_ALPHA_INDEX = 5
IGNORE_PREFIX =
GENERATE_HTML = YES
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
HTML_EXTRA_STYLESHEET =
HTML_EXTRA_FILES =
HTML_COLORSTYLE_HUE = 220
HTML_COLORSTYLE_SAT = 100
HTML_COLORSTYLE_GAMMA = 80
HTML_TIMESTAMP = NO
HTML_DYNAMIC_MENUS = YES
HTML_DYNAMIC_SECTIONS = NO
HTML_INDEX_NUM_ENTRIES = 100
GENERATE_DOCSET = NO
DOCSET_FEEDNAME = "Doxygen generated docs"
DOCSET_BUNDLE_ID = org.doxygen.Project
DOCSET_PUBLISHER_ID = org.doxygen.Publisher
DOCSET_PUBLISHER_NAME = Publisher
GENERATE_HTMLHELP = NO
CHM_FILE =
HHC_LOCATION =
GENERATE_CHI = NO
CHM_INDEX_ENCODING =
BINARY_TOC = NO
TOC_EXPAND = NO
GENERATE_QHP = NO
QCH_FILE =
QHP_NAMESPACE = org.doxygen.Project
QHP_VIRTUAL_FOLDER = doc
QHP_CUST_FILTER_NAME =
QHP_CUST_FILTER_ATTRS =
QHP_SECT_FILTER_ATTRS =
QHG_LOCATION =
GENERATE_ECLIPSEHELP = NO
ECLIPSE_DOC_ID = org.doxygen.Project
DISABLE_INDEX = NO
GENERATE_TREEVIEW = NO
ENUM_VALUES_PER_LINE = 4
TREEVIEW_WIDTH = 250
EXT_LINKS_IN_WINDOW = NO
FORMULA_FONTSIZE = 10
FORMULA_TRANSPARENT = YES
USE_MATHJAX = NO
MATHJAX_FORMAT = HTML-CSS
MATHJAX_RELPATH = https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/
MATHJAX_EXTENSIONS =
MATHJAX_CODEFILE =
SEARCHENGINE = YES
SERVER_BASED_SEARCH = NO
EXTERNAL_SEARCH = NO
SEARCHENGINE_URL =
SEARCHDATA_FILE = searchdata.xml
EXTERNAL_SEARCH_ID =
EXTRA_SEARCH_MAPPINGS =
GENERATE_LATEX = NO
LATEX_OUTPUT = latex
LATEX_CMD_NAME =
MAKEINDEX_CMD_NAME = makeindex
LATEX_MAKEINDEX_CMD = \makeindex
COMPACT_LATEX = NO
PAPER_TYPE = a4
EXTRA_PACKAGES =
LATEX_HEADER =
LATEX_FOOTER =
LATEX_EXTRA_STYLESHEET =
LATEX_EXTRA_FILES =
PDF_HYPERLINKS = YES
USE_PDFLATEX = YES
LATEX_BATCHMODE = NO
LATEX_HIDE_INDICES = NO
LATEX_SOURCE_CODE = NO
LATEX_BIB_STYLE = plain
LATEX_TIMESTAMP = NO
LATEX_EMOJI_DIRECTORY =
GENERATE_RTF = NO
RTF_OUTPUT = rtf
COMPACT_RTF = NO
RTF_HYPERLINKS = NO
RTF_STYLESHEET_FILE =
RTF_EXTENSIONS_FILE =
RTF_SOURCE_CODE = NO
GENERATE_MAN = NO
MAN_OUTPUT = man
MAN_EXTENSION = .3
MAN_SUBDIR =
MAN_LINKS = NO
GENERATE_XML = NO
XML_OUTPUT = xml
XML_PROGRAMLISTING = YES
XML_NS_MEMB_FILE_SCOPE = NO
GENERATE_DOCBOOK = NO
DOCBOOK_OUTPUT = docbook
DOCBOOK_PROGRAMLISTING = NO
GENERATE_AUTOGEN_DEF = NO
GENERATE_PERLMOD = NO
PERLMOD_LATEX = NO
PERLMOD_PRETTY = YES
PERLMOD_MAKEVAR_PREFIX =
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = NO
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED = HDR=1
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
TAGFILES =
GENERATE_TAGFILE =
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
EXTERNAL_PAGES = YES
PERL_PATH = /usr/bin/perl
CLASS_DIAGRAMS = YES
MSCGEN_PATH =
DIA_PATH =
HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = NO
DOT_NUM_THREADS = 0
DOT_FONTNAME = Helvetica
DOT_FONTSIZE = 10
DOT_FONTPATH =
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
UML_LIMIT_NUM_FIELDS = 10
TEMPLATE_RELATIONS = NO
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = NO
CALLER_GRAPH = NO
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
DOT_IMAGE_FORMAT = png
INTERACTIVE_SVG = NO
DOT_PATH =
DOTFILE_DIRS =
MSCFILE_DIRS =
DIAFILE_DIRS =
PLANTUML_JAR_PATH =
PLANTUML_CFG_FILE =
PLANTUML_INCLUDE_PATH =
DOT_GRAPH_MAX_NODES = 50
MAX_DOT_GRAPH_DEPTH = 0
DOT_TRANSPARENT = NO
DOT_MULTI_TARGETS = NO
GENERATE_LEGEND = YES
DOT_CLEANUP = YES

188
source-doc.md Normal file
View File

@ -0,0 +1,188 @@
Welcome to the HyperRogue documentation! {#mainpage}
========================================
Documentation is in progress. Most functions are not explained yet.
Guided Tour
-----------
HyperRogue started as a very simple project: one geometry, one map structure, one
projection, one mechanics, one way to play the game (OK, there were two monster
types). Today, HyperRogue has over 60 lands with unique mechanics, about 40
geometries (including 2D, 3D, and non-isotropic ones) displayed in over 20
projections, many modes which completely change the gameplay, and even non-game
modes for mathematical or data visualization. As a result, it is quite easy to
get lost -- not only because it is a very big project, but also because some of
the early design decisions which were more appropriate for small projects, or
may make some things somewhat illogical now.
Where should one start when reading the source code, then?
The main files which hold everything together are:
* sysconfig.h -- loads libraries, sets various `CAP_*` (capability) compiler flags.
These can be used to enable or disable parts of HyperRogue, due to missing
libraries/hardware capabilities, or to save on compilation time / executable size.
(Not all combinations work.)
* classes.h -- defines enums related to content (lands, walls, monsters, items,
geometries, projections).
* hyper.h -- this defines the basic general templates used everywhere in the game,
as well as macro definitions which change depending on game mode or geometry
(such as `S7` which is the number of edges in the pure geometry, `R10` which is
the number of treasure to collect to advance, or `sphere` which tells us whether
we are playing in spherical geometry), and some chaotic stuff which has not been
moved elsewhere.
* autohdr.h -- this file is generated automatically by `makeh`. It contains the
headers for all the functions and structs defined anywhere in the game (EX and
`#if HDR` tell makeh to put a header for the given entity in autohdr.h), so usually
it is better to read those other files directly.
Interesting CPP files, arranged from the most basic ones:
* hyperpoint.cpp -- computations which make non-Euclidean geometry work. An uniform
system is used for continuous hyperbolic, Euclidean, and spherical geometries,
in 2D and 3D (for nonisotropic geometries see nonisotropic.cpp). The most important
types are hr::hyperpoint (a vector in homogeneous coordinates) and hr::transmatrix
(a matrix).
* locations.cpp -- this defines the abstract classes used for representing maps.
Important types are hr::cell (actual cells used by the game), hr::heptagon
(coarser structure used in the default and some other geometries, this corresponds
to heptagons in the standard geometry, but may have nothing to do with heptagons
in general), and hr::walker (which handle navigation on the map).
* heptagon.cpp -- this builds the structure of heptagons (see [this guide](http://roguetemple.com/z/hyper/dev.php))
in the standard geometries on the hyperbolic planes. Other geometries are built
in different ways, so they do not use this much. This graph is built in an abstract
way, i.e., not using the computations from hyperpoint.cpp.
* cell.cpp -- in the standard map, this builds the actual game graph, by bitruncating
the graph of heptagons (pure geometries are also handled here, but Goldberg and
irregular variations are defined in goldberg.cpp and irregular.cpp).
It also defines the basic class hr::hrmap (used in all kinds of geometries),
hr::hrmap_hyperbolic (used in 2D hyperbolic geometries), and many functions dealing
with the game graph, such as computing the distances.
* classes.cpp and content.cpp -- content.cpp is actual game content (lands, walls,
items, monsters), so if you want to add more, start here. classes.cpp defines
the available geometries and projections, and some extra definitions for game content.
* geometry.cpp -- this specifies how the discrete tessellation from heptagon.cpp and
cell.cpp connects to the underlying continuous geometry (hyperpoint.cpp). More advanced
routines are in geometry2.cpp.
* Low level graphic routines can be found between hypgraph.cpp (implementation of various projections
-- the major projections use GLSL shaders though), shaders.cpp (GLSL shaders and other
low-level OpenGL routines), basegraph.cpp (various basic stuff), drawing.cpp (queue of
objects to draw, special handling for spherical geometries), control.cpp (low-level control).
* graph.cpp deals mostly with drawing high-level objects, such as tiles, monsters, and items.
The shapes themselves are programmed in polygons.cpp, floor shapes are adjusted to various
geometries in floorshapes.cpp.
* game.cpp implements most of the game mechanics. Some mechanics which are more unique to
specific lands are implemented in complex.cpp and complex2.cpp.
* landgen.cpp is basic (local) land generation, while barriers (i.e., Great Walls) are handled
in barriers.cpp, and equidistant surfaces, horocycles etc. are handled in bigstuff.cpp.
* boring utilities include util.cpp (other basic maths and parsing expressions), hprint.cpp
(dealing with files and streams), dialogs.cpp (dialog screens), hyper.cpp and init.cpp
(initialization), system.cpp (starting new games, changing modes etc.).
How to use the HyperRogue engine for making visualizations
----------------------------------------------------------
The HyperRogue engine includes various "hooks" which can be used to extend the game.
For example, a hook can be redefined to add extra commandline parameters, generate
new kinds of hr::hrmap, replace the map-drawing or cell-drawing routines, and so on.
This is used thorough the source code to organize things such as commandline parameters,
and also can be used to experiment with adding new things. Write a cpp file which
includes the file init.cpp (to load all the headers), redefines some hooks (for the
extra functionality), and compile it with the compiler flag `-DCU=1` (so just the headers
are included) and link it to `hyper.o`. Rogueviz works this way.
How to add game content: lands, items, monsters, walls
------------------------------------------------------
The hook system currently does not allow adding new content easily, but you can simply add the new content to the end of the file content.cpp. You also need to do the following:
For Lands:
* Add new entries to hyperrogue-music.txt, these are indexed by integer IDs.
* Create the new monsters (as described below), and add entries to isNative in landlock.cpp.
* Implement the land generation in void giantLandSwitch(cell *c, int d, cell *from) (hint: this function is called for each cell whenever the minimum distance from the player (d) decreases; d=7 are visible and thus they are fully generated)
* You probably want to add some wandering monsters at high treasure counts -- see wandering() in monstergen.cpp
* Add new entries to graph.cpp to draw the new land correctly
* To make the land reachable, you should do the following things: (land unlocking is not factored very well)
* * add entries to getNewLand in landlock.cpp, to make the land actually reachable
* * add entries to land_over in landlock.cpp, which specifies the order in the Land Overview
* * add rules to land_validity if there are any restrictions (note: the default is that there are no restrictions -- the land could appear in Chaos Yendor Challenge)
* You might want to add special cases in functions: earthFloor(), earthWall(), summonedAt(), or add a new Yendor Challenge
* For the Steam version, achievements and leaderboards should be added
For Monsters:
* If it is an enemy monster, you probably want to add an entry to int* killtable[] in games.cpp to make the kills count in total kills
* Add a case to drawMonsterType in graph.cpp -- at first you can just change the colors of an existing monster, adding new graphics is described later
* To save the kill count correctly, add an applyBoxM line to system.cpp, and increase POSSCORE by 1. This has to be added last, to keep compatibility.
Adding Items
* To save the treasure count correctly, add a line applyBoxI(eItem) in system.cpp, and increase POSSCORE by 1
* To save the Orbs correctly, add lines applyBoxOrb(eItem) and list_invorb(); in system.cpp, and increase POSSCORE by 2 (this saves both the current number of charges, and the OSM inventory) This has to be added last, to keep compatibility
* For Orbs, you have to add entries to reduceOrbPowers() (maximum charges) and orbcharges() (charges per Orb) in orbs.cpp
* Treasure pictures are based on the ASCII glyphs by default -- if you want something special, add a case to drawItemType in graph.cpp
Adding Wall Types (i.e., any static objects)
* You need to define how the new wall type reacts to many different effects: boatGoesThrough(), passable(), prespill(), makeflame(), explodeAround(), flashCell(), castLightningBolt(), explodeMine(), summonedAt(), beastcrash()
How to add new graphics
-----------------------
* Draw a picture in the Vector Graphics Editor, and press Shift+S to get the code
* Paste the code into polydata[] in polygons.cpp, but replace ID by NEWSHAPE, (number identifier)
* Add a new shape member (sh*) in hr::geometry_information
* For floor shapes, add a new member of type escher_floorshape in hr::geometry_information, and init_escher() call in init_floorshapes()
(the parameters are the number identifiers from polydata)
* For non-floor shapes, link the new shape global variable to the polydata[] entry in buildpolys() (by calling function bshape)
* Add the code using the new shape variable to graph.cpp
How to add configuration
------------------------
* Add a new variable in struct videopar in hyper.h, or some other place if you prefer
* Provide a default value and config file line in void initConfig() in config.cpp
* Add a menu entry in the appropriate show* function (hint: old code implements the reaction to selecting the menu option as a case in keyhandler -- the new code just calls the add_action function just after showing the menu option, which is more convenient)
Adding new text (including names and descriptions of lands/items/walls/monsters)
--------------------------------------------------------------------------------
* Remember to call XLAT and similar functions instead of writing the text directly, so that it is translated
* It is good to list all the added texts (i.e., possible parameters to XLAT) somewhere, so it can be translated
How to add new projections
--------------------------
This is simple (well, in the easy cases) -- add new entry to classes.h (enum eModel), classes.cpp (hr::mdinf), and implement your projection in applymodel() in hypgraph.cpp.
How to add new geometries (i.e., map structures)
------------------------------------------
Well, this is ambitious.
* Add new entry to classes.h (enum eGeometry), classes.cpp (hr::ginf) marking your geometry as "EXPERIMENTAL".
* Implement a new subclass of hr::hrmap. hr::hrmap_binary in binary-tiling.cpp is a good guide.
* If you use the standard bitruncation, or cells correspond 1-1 to heptagons, you do not have to do anything (well, you may need to automatically disable bitruncation in
\link hr::set_geometry() \endlink).
Otherwise modifying \link hr::createMov() \endlink may be necessary.
* Modify initcells() (or define a hook) to actually create a map in your subclass.
* For 3D geometries you need to tell HyperRogue the shape of the faces. See geometry_information::create_wall3d() in polygons.cpp.
* For 2D geometries you need to tell HyperRogue how to draw the cells (see floorshapes.cpp) and various geometry details in geometry2.cpp.
* Add an entry in geom-exp.cpp to make your geometry available (otherwise it can be activated with the command line option `-geo NameOfMyGeometry`).
* Once the basic geometry works, you can disable the experimental status of your geometry, and try making things in cell.cpp (such as cell distances) and bigstuff.cpp
(large scale land generation) work.