diff --git a/.gitignore b/.gitignore index e1abcaa63..51b8c1f0f 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,7 @@ prebuilt ## doxygen Doxygen +!docs/cs-manual/Makefile ## ides/editors *~ diff --git a/AUTHORS.md b/AUTHORS.md index 83a625406..79cb87e64 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -128,6 +128,7 @@ Manual Bodillium Cramal + Alejandro Sanchez (HiPhish) sir_herrbatka Packagers diff --git a/docs/cs-manual/Makefile b/docs/cs-manual/Makefile new file mode 100644 index 000000000..9d62dc5ab --- /dev/null +++ b/docs/cs-manual/Makefile @@ -0,0 +1,216 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/OpenMWCSManual.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/OpenMWCSManual.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/OpenMWCSManual" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/OpenMWCSManual" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/cs-manual/make.bat b/docs/cs-manual/make.bat new file mode 100644 index 000000000..744d60007 --- /dev/null +++ b/docs/cs-manual/make.bat @@ -0,0 +1,263 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source +set I18NSPHINXOPTS=%SPHINXOPTS% source +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + echo. coverage to run coverage check of the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +REM Check if sphinx-build is available and fallback to Python version if any +%SPHINXBUILD% 1>NUL 2>NUL +if errorlevel 9009 goto sphinx_python +goto sphinx_ok + +:sphinx_python + +set SPHINXBUILD=python -m sphinx.__init__ +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +:sphinx_ok + + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\OpenMWCSManual.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\OpenMWCSManual.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "coverage" ( + %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage + if errorlevel 1 exit /b 1 + echo. + echo.Testing of coverage in the sources finished, look at the ^ +results in %BUILDDIR%/coverage/python.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/docs/cs-manual/source/_static/images/chapter-1/add-record.png b/docs/cs-manual/source/_static/images/chapter-1/add-record.png new file mode 100644 index 000000000..c0a110b7c Binary files /dev/null and b/docs/cs-manual/source/_static/images/chapter-1/add-record.png differ diff --git a/docs/cs-manual/source/_static/images/chapter-1/edit-record.png b/docs/cs-manual/source/_static/images/chapter-1/edit-record.png new file mode 100644 index 000000000..4db3d1bd6 Binary files /dev/null and b/docs/cs-manual/source/_static/images/chapter-1/edit-record.png differ diff --git a/docs/cs-manual/source/_static/images/chapter-1/new-project.png b/docs/cs-manual/source/_static/images/chapter-1/new-project.png new file mode 100644 index 000000000..a5097db9c Binary files /dev/null and b/docs/cs-manual/source/_static/images/chapter-1/new-project.png differ diff --git a/docs/cs-manual/source/_static/images/chapter-1/objects.png b/docs/cs-manual/source/_static/images/chapter-1/objects.png new file mode 100644 index 000000000..f36a7289c Binary files /dev/null and b/docs/cs-manual/source/_static/images/chapter-1/objects.png differ diff --git a/docs/cs-manual/source/_static/images/chapter-1/opening-dialogue.png b/docs/cs-manual/source/_static/images/chapter-1/opening-dialogue.png new file mode 100644 index 000000000..5356c2695 Binary files /dev/null and b/docs/cs-manual/source/_static/images/chapter-1/opening-dialogue.png differ diff --git a/docs/cs-manual/source/conf.py b/docs/cs-manual/source/conf.py new file mode 100644 index 000000000..28931a4a0 --- /dev/null +++ b/docs/cs-manual/source/conf.py @@ -0,0 +1,358 @@ +# -*- coding: utf-8 -*- +# +# OpenMW CS Manual documentation build configuration file, created by +# sphinx-quickstart on Fri Feb 5 21:28:27 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'OpenMW CS Manual' +copyright = u'2016, The OpenMW Project' +author = u'HiPhish' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'0.0' +# The full version, including alpha/beta/rc tags. +release = u'0.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'OpenMWCSManualdoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'OpenMWCSManual.tex', u'OpenMW CS Manual Documentation', + u'HiPhish', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'openmwcsmanual', u'OpenMW CS Manual Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'OpenMWCSManual', u'OpenMW CS Manual Documentation', + author, 'OpenMWCSManual', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + + +# -- Options for Epub output ---------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project +epub_author = author +epub_publisher = author +epub_copyright = copyright + +# The basename for the epub file. It defaults to the project name. +#epub_basename = project + +# The HTML theme for the epub output. Since the default themes are not +# optimized for small screen space, using the same theme for HTML and epub +# output is usually not wise. This defaults to 'epub', a theme designed to save +# visual space. +#epub_theme = 'epub' + +# The language of the text. It defaults to the language option +# or 'en' if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# A sequence of (type, uri, title) tuples for the guide element of content.opf. +#epub_guide = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files that should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Choose between 'default' and 'includehidden'. +#epub_tocscope = 'default' + +# Fix unsupported image types using the Pillow. +#epub_fix_images = False + +# Scale large images. +#epub_max_image_width = 0 + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#epub_show_urls = 'inline' + +# If false, no index is generated. +#epub_use_index = True + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/docs/cs-manual/source/files-and-directories.rst b/docs/cs-manual/source/files-and-directories.rst new file mode 100644 index 000000000..34680fa94 --- /dev/null +++ b/docs/cs-manual/source/files-and-directories.rst @@ -0,0 +1,224 @@ +Files and Directories +##################### + +In this chapter of the manual we will cover the usage of files and directories +by OpenMW CS. Files and directories are file system concepts of your operating +system, so we will not be going into specifics about that, we will only focus +on what is relevant to OpenMW CS. + + +Basics +****** + + +Directories +=========== + +OpenMW and OpenMW CS us multiple directories on the file system. First of all +there is a *user directory* that holds configuration files and a number of +different sub-directories. The location of the user directory is hard-coded +into the CS and depends on your operating system. + +================ ========================================= +Operating System User Dircetory +================ ========================================= +GNU/Linux ```` +OS X ``~/Library/Application Support/openmw/`` +Windows ```` +================ ========================================= + +In addition to to this single hard-coded directory both OpenMW and OpenMW CS +need a place to seek for a actuals data files of the game: textures, 3D models, +sounds and record files that store objects in game; dialogues an so one. These +files are called *content files*. We support multiple such paths (we call them +*data paths*) as specified in the configuration. Usually one data path points +to the directory where the original Morrowind game is either installed or +unpacked to. You are free to specify as many data paths as you would like, +however, there is one special data path that, as described later, which is used +to store newly created content files. + + +Content files +============= + +The original Morrowind engine by Bethesda Softworks uses two types of content +files: `esm` (master) and `esp` (plugin). The distinction between those two is +not clear, and often confusing. One would expect the `esm` (master) file to be +used to specify one master, which is then modified by the `esp` plugins. And +indeed: this is the basic idea. However, the official expansions were also made +as ESM files, even though they could essentially be described as really large +plugins, and therefore would rather use `esp` files. There were technical +reasons behind this decision – somewhat valid in the case of the original +engine, but clearly it is better to create a system that can be used in a more +sensible way. OpenMW achieves this with our own content file types. + +We support both ESM and ESP files, but in order to make use of new features in +OpenMW one should consider using new file types designed with our engine in +mind: *game* files and *addon* files, collectively called *content files*. + + +OpenMW content files +-------------------- + +The concepts of *Game* and *Addon* files are somewhat similar to the old +concept of *ESM* and *ESP*, but more strictly enforced. It is quite +straight-formward: If you want to make new game using OpenMW as the engine (a +so called *total conversion*) you should create a game file. If you want to +create an addon for an existing game file create an addon file. Nothing else +matters; the only distinction you should consider is if your project is about +changing another game or creating a new one. Simple as that. + +Another simple thing about content files are the extensions: we are using +``.omwaddon`` for addon files and ``.omwgame`` for game files. + + +Morrowind content files +----------------------- + +Using our content files is recommended for projects that are intended to used +with the OpenMW engine. However, some players might wish to still use the +original Morrowind engine. In addition thousands of *ESP*/*ESM* files were +created since 2002, some of them with really outstanding content. Because of +this OpenMW CS simply has no other choice but to support *ESP*/*ESM* files. If +you decid to choose *ESP*/*ESM* file instead of using our own content file +types you are most likely aimng at compatibility with the original engine. This +subject is covered in it own chapter of this manual. + + +.. TODO This paragraph sounds weird + +The actual creation of new files is described in the next chapter. Here we are +going to focus only on the details you need to know in order to create your +first OpenMW CS file while fully understanding your needs. For now let’s jut +remember that content files are created inside the user directory in the the +``data`` subdirectory (that is the one special data directory mentioned +earlier). + + +Dependencies +------------ + +Since an addon is supposed to change the game it follows that it also depends +on the said game to work. We can conceptualise this with an examples: your +modification is the changing prize of an iron sword, but what if there is no +iron sword in game? That's right: we get nonsense. What you want to do is tie +your addon to the files you are changing. Those can be either game files (for +example when making an expansion island for a game) or other addon files +(making a house on said island). Obviously It is a good idea to be dependent +only on files that are really changed in your addon, but sadly there is no +other way to achieve this than knowing what you want to do. Again, please +remember that this section of the manual does not cover creating the content +files – it is only a theoretical introduction to the subject. For now just keep +in mind that dependencies exist, and is up to you to decide whether your +content file should depend on other content files. + +Game files are not intend to have any dependencies for a very simple reasons: +the player is using only one game file (excluding original and the dirty +ESP/ESM system) at a time and therefore no game file can depend on other game +file, and since a game file makes the base for addon files it can not depend on +addon files. + + +Project files +------------- + +Project files act as containers for data not used by the OpenMW game engine +itself, but still useful for OpenMW CS. The shining example of this data +category are without doubt record filters (described in a later chapter of the +manual). As a mod author you probably do not need or want to distribute project +files at all, they are meant to be used only by you and your team. + +.. TODO "you and your team": is that correct? + +As you would imagine, project files make sense only in combination with actual +content files. In fact, each time you start to work on new content file and a +project file was not found, one will be created. The extensio of project files +is ``.project``. The whole name of the project file is the whole name of the +content file with appended extension. For instance a ``swords.omwaddon`` file +is associated with a ``swords.omwaddon.project`` file. + +Project files are stored inside the user directory, in the ``projects`` +subdirectory. This is the path location for both freshly created project files, +and a place where OpenMW CS looks for already existing files. + + +Resource files +============== + +.. TODO This paragraph sounds weird + +Unless we are talking about a fully text based game, like Zork or Rogue, one +would expect that a video game is using some media files: 3D models with +textures, images acting as icons, sounds and anything else. Since content +files, no matter whether they are *ESP*, *ESM* or new OpenMW file type, do not +contain any of those, it is clear that they have to be delivered with a +different file. It is also clear that this, let’s call it “resources file“, +has to be supported by the engine. Without code handling those files it is +nothing more than a mathematical abstraction – something, that lacks meaning +for human beings. Therefore this section must cover ways to add resources +files to your content file, and point out what is supported. We are going to do +just that. Later, you will learn how to make use of those files in your +content. + + +Audio +----- + +OpenMW uses FFmpeg_ for audio playback, and so we support every audio type +supported by that library. This makes a huge list. Below is only small portion +of the supported file types. + +mp3 (MPEG-1 Part 3 Layer 3) + A popular audio file format and de facto standard for storing audio. Used by + the Morrowind game. + +ogg + An open source, multimedia container file using a high quality Vorbis_ audio + codec. Recommended. + + +Video +----- + +Video As in the case of audio files, we are using FFmepg to decode video files. +The list of supported files is long, we will cover only the most significant. + +bik + Videos used by the original Morrowind game. + +mp4 + A multimedia container which use more advanced codecs (MPEG-4 Parts 2, 3 and + 10) with a better audio and video compression rate, but also requiring more + CPU intensive decoding – this makes it probably less suited for storing + sounds in computer games, but good for videos. + +webm + A new, shiny and open source video format with excellent compression. It + needs quite a lot of processing power to be decoded, but since game logic is + not running during cutscenes we can recommend it for use with OpenMW. + +ogv + Alternative, open source container using Theora_ codec for video and Vorbis for audio. + + + +Textures and images +------------------- + +The original Morrowind game uses *DDS* and *TGA* files for all kinds of two +dimensional images and textures alike. In addition, the engine supported *BMP* +files for some reason (*BMP* is a terrible format for a video game). We also +support an extended set of image files – including *JPEG* and *PNG*. *JPEG* and +*PNG* files can be useful in some cases, for instance a *JPEG* file is a valid +option for skybox texture and *PNG* can useful for masks. However, please keep +in mind that *JPEG* images can grow to large sizes quickly and are not the best +option with a DirectX rendering backend. You probably still want to use *DDS* +files for textures. + + + +.. Hyperlink targets for the entire document + +.. _FFmpeg: http://ffmpeg.org +.. _Vorbis: http://www.vorbis.com +.. _Theora: http://www.theora.org diff --git a/docs/cs-manual/source/foreword.rst b/docs/cs-manual/source/foreword.rst new file mode 100644 index 000000000..613eca5e3 --- /dev/null +++ b/docs/cs-manual/source/foreword.rst @@ -0,0 +1,21 @@ +Foreword +######## + + + + +How to read the manual +********************** + +The manual can be roughly divided into two parts: a tutorial part consisting of +the first two (three) chapters and the reference manual. We recommend all +readers to work through the tutorials first, there you will be guided through +the creation of a fairly simple mod where you can familiarise yourself with the +record-based interface. The tutorials are very simple and teach you only what +is necessary for the task, each one can be completed in under half an hour. It +is strongly recommended to do the tutorials in order. + +When you are familiar with the CS in general and want to write your own mods it +is time to move on to the reference part of the manual. The reference chapters +can be read out of order, each one covers only one topic. + diff --git a/docs/cs-manual/source/index.rst b/docs/cs-manual/source/index.rst new file mode 100644 index 000000000..ce50b8c95 --- /dev/null +++ b/docs/cs-manual/source/index.rst @@ -0,0 +1,30 @@ +.. OpenMW CS Manual documentation master file, created by + sphinx-quickstart on Fri Feb 5 21:28:27 2016. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +##################### +OpenMW CS user manual +##################### + +The following document is the complete user manual for *OpenMW CS*, the +construction set for the OpenMW game engine. It is intended to serve both as an +introduction and a reference for the application. Even if you are familiar with +modding *The Elder Scrolls III: Morrowind* you should at least read the first +few chapters to familiarise yourself with the new interface. + +.. warning:: + OpenMW CS is still software in development. The manual does not cover any of + its shortcomings, it is written as if everything was working as inteded. + Please report any software problems as bugs in the software, not errors in + the manual. + +.. toctree:: + :caption: Table of Contents + :maxdepth: 2 + + foreword + tour + files-and-directories + starting-dialog + diff --git a/docs/cs-manual/source/starting-dialog.rst b/docs/cs-manual/source/starting-dialog.rst new file mode 100644 index 000000000..02a65ff21 --- /dev/null +++ b/docs/cs-manual/source/starting-dialog.rst @@ -0,0 +1,40 @@ +OpenMW CS Starting Dialog +######################### + +In this chapter we will cover starting up OpenMW CS and the starting interface. +Start the CS the way intended for your operating system and you will be +presented with window and three main buttons and a small button with a +wrench-icon. The wrench will open the configuration dialog which we will cover +later. The three main buttons are the following: + +Create A New Game + Choose this option if you want to create an original game that does not + depend on any other content files. The distinction between game and addon in + the original Morrowind engine was somewhat blurry, but OpenMW is very strict + about it: regardless of how large your addon is, if it depends on another + content file it is not an original game. + +Create A New Addon + Choose this option if you want to create an extension to an existing game. + An addon can depend on other addons as well optionally, but it *must* depend + on a game. + +Edit A Content File + Choose this option is you wish to edit an existing content file, regardless + of whether it is a game or an addon. + +Whether you create a game or an addon, a data file and a project file will be +generated for you in you user directory. + +You will have to choose a name for your content file and if you chose to create +an addon you will also have to chose a number of dependencies. You have to +choose exactly one game and you can choose an arbitrary amount of addon +dependencies. For the sake of simplicity and maintainability choose only the +addons you actually want to depend on. Also keep in mind that your dependencies +might have dependencies of their own, you have to depend on those as well. If +one of your dependencies nees something it will be indicated by a warning sign +and automatically include its dependencies when you choose it. + +If you want to edit an existing content file you will be presented with a +similar dialog, except you don't get to choose a file name (because you are +editing files that already exist). diff --git a/docs/cs-manual/source/tour.rst b/docs/cs-manual/source/tour.rst new file mode 100644 index 000000000..0e92fe6fa --- /dev/null +++ b/docs/cs-manual/source/tour.rst @@ -0,0 +1,223 @@ +A Tour through OpenMW CS: making a magic ring +############################################# + +In this first chapter we will create a mod that adds a new ring with a simple +enchantment to the game. The ring will give its wearer a permanent Night Vision +effect while being worn. You don't need prior knowledge about modding +Morrowind, but you should be familiar with the game itself. There will be no +scripting necessary, we chan achieve everything using just what the base game +offers out of the box. Before continuing make sure that OpenMW is properly +installed and playable. + + +Adding the ring to the game's records +************************************* + +In this first section we will define what our new ring is, what it looks like +and what it does. Getting it to work is the first step before we go further. + + +Starting up OpenMW CS +===================== + +We will start by launching OpenMW CS, the location of the program depends on +your operating system. You will be presented with a dialogue with three +options: create a new game, create a new addon, edit a content file. + +.. figure:: ./_static/images/chapter-1/opening-dialogue.png + :alt: Opening dialogue with three option and setting button (the wrench) + +The first option is for creating an entirely new game, that's not what we want. +We want to edit an existing game, so choose the second one. When you save your +addon you can use the third option to open it again. + +You will be presented with another window where you get to chose the content to +edit and the name of your project. We have to chose at least a base game, and +optionally a number of other addons we want to depend on. The name of the +project is arbitrary, it will be used to identify the addon later in the OpenMW +launcher. + +.. figure:: ./_static/images/chapter-1/new-project.png + :alt: Creation dialogue for a new project, pick content modules and name + +Choose Morrowind as your content file and enter `Ring of Night Vision` as the +name. We could also chose further content files as dependencies if we wanted +to, but for this mod the base game is enough. + +Once the addon has been created you will be presented with a table. If you see +a blank window rather than a table choose *World* → *Objects* from the menu. + +.. figure:: ./_static/images/chapter-1/objects.png + :alt: The table showing all objet records in the game. + +Let's talk about the interface for a second. Every window in OpenMW CS has +*panels*, these are often but not always tables. You can close a panel by +clicking the small "X" on the title bar of the panel, or you can detach it by +either dragging the title bar or clicking the icon with the two windows. A +detached panel can be re-attached to a window by dragging it by the title bar +on top of the window. + +Now let's look at the panel itself: we have a filter text field, a very large +table and a status bar. The filter will be very useful when we want to find an +entry in the table, but for now it is irrelevant. The table you are looking at +contains all objects in the game, these can be items, NPCs, creatures, +whatever. Every object is an entry in that table, visible as a row. The columns +of the table are the attributes of each object. + +Morrowind uses something called a *relational database* for game data. If you +are not familiar with the term, it means that every type of thing can be +expressed as a *table*: there is a table for objects, a table for enchantments, +a table for icons, one for meshes, and so on. Properties of an entry must be +simple values, like numbers or text strings. If we want a more complicated +property we need to reference an entry from another table. There are a few +exceptions to this though, some tables do have subtables. The effects of +enchantments are one of those exceptions. + + +Defining a new record +===================== + +Enough talk, let's create the new ring now. Right-click anywhere in the objects +table, choose `Add Record` and the status bar will change into an input field. +We need to enter an *ID* (short for *identifier*) and pick the type. The +identifier is a unique name by which the ring can later be identified; I have +chosen `ring_night_vision`. For the type choose *Clothing*. + +.. figure:: ./_static/images/chapter-1/add-record.png + :alt: Enter the ID and type of the new ring + +The table should jump right to our newly created record, if not read further +below how to use filters to find a record by ID. Notice that the *Modified* +column now shows that this record is new. Records can also be *Base* +(unmodified), *Modified* and *Deleted*. The other fields are still empty since +we created this record from nothing. We can double-click a table cell while +holding Shift to edit it (this is a configurable shortcut), but there is a +better way: right-click the row of our new record and chose *Edit Record*, a +new panel will open. + +We can right-click the row of our new record and chose *Edit Record*, a +new panel will open. Alternatively we can also define a configurable shortcut +instead of using the context menu; the default is double-clicking while +holding down the shift key. + + +.. figure:: ./_static/images/chapter-1/edit-record.png + :alt: Edit the properties of the record in a separate panel + +You can set the name, weight and coin value as you like, I chose `Ring of Night +Vision`, `0.1` and `2500` respectively. Make sure you set the *Clothing Type* +to *Ring*. We could set the other properties manually as well, but unless you +have an exceptional memory for identifiers and never make typos that's not +feasible. What we are going to do instead is find the records we want in their +respective tables and assign them from there. + + +Finding records using filters +============================= + +We will add an icon first. Open the *Icons* table the same way you opened the +*Objects* table: in the menu click *Assets* → *Icons*. If the window gets too +crowded remember that you can detach panels. The table is huge and not every +ring icon starts with "ring", so we have to use filters to find what we want. + +Filters are a central element of OpenMW CS and a major departure from how the +original Morrowind CS was used. In fact, filters are so important that they +have their own table as well. We won't be going that far for now though. There +are three types of filters: *Project filters* are part of the project and are +stored in the project file, *session filter* are only valid until you exit the +CS, and finally *instant filter* which are used only once and typed directly +into the *Filter* field. + +For this tutorial we will only use instant filters. We type the definition of +the filter directly into the filter field rather than the name of an existing +filter. To signify that we are using an instant filter the have to use `!` as +the first character. Type the following into the field: + +.. code:: + + !string("id", ".*ring.*") + +A filter is defined by a number of *queries* which can be logically linked. For +now all that matters is that the `string(, )` query will check +whether `` matches ``. The pattern is a regular expression, +if you don't know about them you should learn their syntax. For now all that +matters is that `.` stands for any character and `*` stands for any amount, +even zero. In other words, we are looking for all entries which have an ID that +contains the word "ring" somewhere in it. This is a pretty dumb pattern because +it will also match words like "ringmail", but it's good enough for now. + +If you have typed the filter definition properly the text should change from +red to black and our table will be narrowed down a lot. Browse for an icon you +like and drag & drop its table row onto the *Icon* field of our new ring. + +That's it, you have now assigned a reference to an entry in another table to +the ring entry in the *Objects* table. Repeat the same process for the 3D +model, you can find the *Meshes* table under *Assets* → *Meshes*. + + +Adding the enchantment +====================== + +Putting everything you have learned so far to practice we can add the final and +most important part to our new ring: the enchantment. You know enough to +perform the following steps without guidance: Open the *Enchantments* table +(*Mechanics* → *Enchantments*) and create a new entry with the ID `Cats Eye`. +Edit it so that it has *Constant Effect* enchantment type. + +To add an effect to the enchantment right-click the *Magic Effects* table and +choose *Add new row*. You can edit the effects by right-clicking their table +cells. Set the effect to *NightEye*, range to *Self*, and both magnitudes to +`50`. The other properties are irrelevant. + +Once you are done add the new enchantment to our ring. That's it, we now have a +complete enchanted ring to play with. Let's take it for a test ride. + + +Playing your new addon +====================== + +Launch OpenMW and in the launcher under *Data Files* check your addon. Load a +game and open the console. We have only defined the ring, but we haven't placed +any instance of it anywhere in the game world, so we have to create one. In the +console type: + +.. code:: + + player->AddItem "ring_night_vision" 1 + +The part in quotation marks is the ID of our ring, you have to adjust it if you +chose a different ID. Exit the console and you should find a new ring in your +inventory. Equip it and you will instantly receive the *Night Vision* effect +for your character. + + +Conclusion +========== + +In this tutorial we have learned how to create a new addon, what tables are and +how to create new records. We have also taken a very brief glimpse at the +syntax of filters, a feature you will be using a lot when creating larger mods. + +This mod is a pure addition, it does not change any of the existing records. +However, if you want to actually present appealing content to the player rather +than just offering abstract definitions you will have to change the game's +content. In the next tutorial we will learn how to place the ring in the game +world so the player can find it legitimately. + + + +Adding the ring to the game's world +*********************************** + +Now that we have defined the ring it is time add it to the game world so the +player can find it legitimately. We will add the ring to a merchant, place it +in a chest and put it somewhere in plain sight. To this end we will have to +actually modify the contents of the game. + + +Subsection to come... +===================== + + + +