diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 962b34f516..926dd3dbf6 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -10,4 +10,4 @@ python: build: os: ubuntu-22.04 tools: - python: "3.8" + python: "3.9" diff --git a/apps/openmw/mwlua/README.md b/apps/openmw/mwlua/README.md index ed911eb01d..a1cfeb1f1b 100644 --- a/apps/openmw/mwlua/README.md +++ b/apps/openmw/mwlua/README.md @@ -3,7 +3,7 @@ This folder contains the C++ implementation of the Lua scripting system. For user-facing documentation, see -[OpenMW Lua scripting](https://openmw.readthedocs.io/en/latest/reference/lua-scripting/index.html). +[Lua scripting](https://openmw.readthedocs.io/en/latest/reference/lua-scripting/index.html). The documentation is generated from [/docs/source/reference/lua-scripting](/docs/source/reference/lua-scripting). You can find instructions for generating the documentation at the diff --git a/docs/requirements.txt b/docs/requirements.txt index f46cc5c95d..d22bcceae6 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -2,4 +2,5 @@ parse_cmake sphinx==7.1.2 docutils==0.18.1 jinja2==3.1.6 -sphinx_rtd_theme==3.0.1 +sphinx-design==0.5.0 +git+https://github.com/glassmancody/sphinxawesome-theme.git@openmw \ No newline at end of file diff --git a/docs/source/_ext/omw-directives.py b/docs/source/_ext/omw-directives.py new file mode 100644 index 0000000000..245c84ad7a --- /dev/null +++ b/docs/source/_ext/omw-directives.py @@ -0,0 +1,76 @@ +from docutils import nodes +from docutils.parsers.rst import Directive, directives + +class OMWSettingDirective(Directive): + has_content = True + option_spec = { + 'title': directives.unchanged_required, + 'type': directives.unchanged_required, + 'range': directives.unchanged, + 'default': directives.unchanged, + 'location': directives.unchanged, + } + + badge_map = { + 'float32': 'bdg-secondary', 'float64': 'bdg-muted', + 'int': 'bdg-primary', 'uint': 'bdg-light', + 'string': 'bdg-success', 'boolean': 'bdg-warning', + 'color': 'bdg-info', + } + + def run(self): + opts = self.options + title = opts['title'] + type_tags = opts['type'].split('|') + badges = ' '.join(f':{self.badge_map.get(t)}:`{t}`' for t in type_tags) + + values = [ + badges, + opts.get('range', ''), + opts.get('default', ''), + opts.get('location', ':bdg-danger:`user settings.cfg`') + ] + + table = nodes.table(classes=['omw-setting']) + tgroup = nodes.tgroup(cols=4) + table += tgroup + for _ in range(4): + tgroup += nodes.colspec(colwidth=20) + + thead = nodes.thead() + tgroup += thead + thead += nodes.row('', *[ + nodes.entry('', nodes.paragraph(text=label)) + for label in ['Type', 'Range', 'Default', 'Location'] + ]) + + tbody = nodes.tbody() + tgroup += tbody + row = nodes.row() + + for i, val in enumerate(values): + entry = nodes.entry() + inline, _ = self.state.inline_text(val, self.lineno) + if i == 2 and 'color' in type_tags: + rgba = [float(c) for c in opts['default'].split()] + style = f'background-color:rgba({rgba[0]*255}, {rgba[1]*255}, {rgba[2]*255}, {rgba[3]})' + chip = nodes.raw('', f'', format='html') + wrapper = nodes.container(classes=['type-color-wrapper'], children=[chip] + inline) + entry += wrapper + else: + entry += inline + row += entry + tbody += row + + desc = nodes.paragraph() + self.state.nested_parse(self.content, self.content_offset, desc) + + section = nodes.section(ids=[nodes.make_id(title)]) + section += nodes.title(text=title) + section += table + section += desc + return [section] + +def setup(app): + app.add_css_file("omw-directives.css") + app.add_directive("omw-setting", OMWSettingDirective) diff --git a/docs/source/_static/luadoc.css b/docs/source/_static/luadoc.css index aa83013def..b2efec85b4 100644 --- a/docs/source/_static/luadoc.css +++ b/docs/source/_static/luadoc.css @@ -1,113 +1,87 @@ -#luadoc tt { font-family: monospace; } - -#luadoc p, -#luadoc td, -#luadoc th { font-size: .95em; line-height: 1.2em;} - -#luadoc p, -#luadoc ul -{ margin: 10px 0 0 10px;} - -#luadoc strong { font-weight: bold;} - -#luadoc em { font-style: italic;} - -#luadoc h1 { - font-size: 1.5em; - margin: 25px 0 20px 0; -} -#luadoc h2, -#luadoc h3, -#luadoc h4 { margin: 15px 0 10px 0; } -#luadoc h2 { font-size: 1.25em; } -#luadoc h3 { font-size: 1.15em; } -#luadoc h4 { font-size: 1.06em; } - -#luadoc hr { - color:#cccccc; - background: #00007f; - height: 1px; -} - -#luadoc blockquote { margin-left: 3em; } - -#luadoc ul { list-style-type: disc; } - -#luadoc p.name { - font-family: "Andale Mono", monospace; - padding-top: 1em; -} - -#luadoc p:first-child { - margin-top: 0px; -} - -#luadoc table.function_list { - border-width: 1px; - border-style: solid; - border-color: #cccccc; - border-collapse: collapse; -} -#luadoc table.function_list td { - border-width: 1px; - padding: 3px; - border-style: solid; - border-color: #cccccc; -} - -#luadoc table.function_list td.name { background-color: #f0f0f0; } -#luadoc table.function_list td.summary { width: 100%; } - -#luadoc dl.table dt, -#luadoc dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;} -#luadoc dl.table dd, -#luadoc dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;} -#luadoc dl.table h3, -#luadoc dl.function h3 {font-size: .95em;} - - - -#luadoc pre.example { - background-color: #eeffcc; - border: 1px solid #e1e4e5; - padding: 10px; - margin: 10px 0 10px 0; - overflow-x: auto; -} - -#luadoc code { - background-color: inherit; - color: inherit; - border: none; - font-family: monospace; +#luadoc code, #luadoc tt, #luadoc p em { + font-family: 'JetBrains Mono', monospace; } #luadoc pre.example code { - color: #404040; - background-color: #eeffcc; - border: none; white-space: pre; - padding: 0px; } -#luadoc dt { - background: inherit; +#luadoc code:not([class*="language-"]) { + background-color: unset; +} + +#luadoc pre:not([class*="language-"]) { + background-color: inherit; color: inherit; - width: 100%; - padding: 0px; + border: none; } -#luadoc a:not(:link) { - font-weight: bold; - color: #000; +#luadoc pre code { + white-space: normal; +} + +#content #luadoc code a:not(.toc-backref) { + font-weight: 600; +} + +#luadoc > p:nth-child(1) { + margin: 12px 0 12px 0; +} + +#luadoc a:not([href]) { text-decoration: none; cursor: inherit; + color: inherit; } -#luadoc a:link { font-weight: bold; color: #004080; text-decoration: none; } -#luadoc a:visited { font-weight: bold; color: #006699; text-decoration: none; } -#luadoc a:link:hover { text-decoration: underline; } -#luadoc dl, -#luadoc dd {margin: 0px; line-height: 1.2em;} +#luadoc a:not([href]):hover { + color: inherit; +} + +#luadoc code a em { + color: inherit; + font-weight: inherit; +} + +#luadoc em { + font-size: 13px; + font-style: normal; +} + +.context-wrapper { + display: flex; + margin-top: 14px; + gap: 4px; +} + +#luadoc ul { list-style-type: disc; } #luadoc li {list-style: bullet;} +#luadoc .function a:not(.toc-backref) { + font-weight: 500; +} + +#content #luadoc dl.function dt:not(.sig):first-child { + border-bottom: 2px solid hsl(var(--muted) / 50%); + background-color: hsl(var(--muted)); + padding: 6px; +} + +#content #luadoc dl.function dt:not(.sig):first-child a { + text-decoration: none; +} + +@media (prefers-color-scheme: dark) { + #content #luadoc dl.function dt:not(.sig):first-child { + border-bottom: 2px solid hsl(var(--accent) / 50%); + background-color: hsl(var(--accent)); + } +} + +#luadoc .table-wrapper.container { + padding: 0; +} + +table.docutils { + width: 100%; +} \ No newline at end of file diff --git a/docs/source/_static/omw-directives.css b/docs/source/_static/omw-directives.css new file mode 100644 index 0000000000..38f6218025 --- /dev/null +++ b/docs/source/_static/omw-directives.css @@ -0,0 +1,21 @@ +.omw-setting td:nth-child(1) { width: 20%; } +.omw-setting td:nth-child(2) { width: 20%; } +.omw-setting td:nth-child(3) { width: 20%; } +.omw-setting td:nth-child(4) { width: 20%; } + +.omw-setting .type-color-wrapper { + display: flex; + flex-direction: row; + align-items: center; + justify-content: left; + padding: 0; + gap: 12px; +} + +.color-chip { + display: inline-block; + width: 1.5em; + height: 1.5em; + border-radius: 0.2em; + border: 1px solid #333; +} diff --git a/docs/source/_static/prism-dark.css b/docs/source/_static/prism-dark.css new file mode 100644 index 0000000000..293a0d1267 --- /dev/null +++ b/docs/source/_static/prism-dark.css @@ -0,0 +1,156 @@ +@media (prefers-color-scheme: dark) { + + /** + * Github Dark theme for Prism.js + * Based on Github: https://github.com + * @author Katorly + */ + /* General */ + pre[class*="language-"], + code[class*="language-"] { + color: #c9d1d9; + font-size: 13px; + text-shadow: none; + font-family: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace; + direction: ltr; + text-align: left; + white-space: pre; + word-spacing: normal; + word-break: normal; + line-height: 1.5; + -moz-tab-size: 4; + -o-tab-size: 4; + tab-size: 4; + -webkit-hyphens: none; + -moz-hyphens: none; + -ms-hyphens: none; + hyphens: none; + } + + pre[class*="language-"]::selection, + code[class*="language-"]::selection, + pre[class*="language-"]::mozselection, + code[class*="language-"]::mozselection { + text-shadow: none; + background: #234879; + } + + @media print { + + pre[class*="language-"], + code[class*="language-"] { + text-shadow: none; + } + } + + pre[class*="language-"] { + padding: 1em; + margin: .5em 0; + overflow: auto; + background: #161b22; + } + + :not(pre)>code[class*="language-"] { + padding: .1em .3em; + border-radius: .3em; + color: #c9d1d9; + background: #343942; + } + + /* Line highlighting */ + pre[data-line] { + position: relative; + } + + pre[class*="language-"]>code[class*="language-"] { + position: relative; + z-index: 1; + } + + .line-highlight { + position: absolute; + left: 0; + right: 0; + padding: inherit 0; + margin-top: 1em; + background: #2f2a1e; + box-shadow: inset 5px 0 0 #674c16; + z-index: 0; + pointer-events: none; + line-height: inherit; + white-space: pre; + } + + /* Tokens */ + .namespace { + opacity: .7; + } + + .token.comment, + .token.prolog, + .token.doctype, + .token.cdata { + color: #8b949e; + } + + .token.punctuation { + color: #c9d1d9; + } + + .token.property, + .token.tag, + .token.boolean, + .token.number, + .token.constant, + .token.symbol, + .token.deleted { + color: #79c0ff; + } + + .token.selector, + .token.attr-name, + .token.string, + .token.char, + .token.builtin, + .token.inserted { + color: #a5d6ff; + } + + .token.operator, + .token.entity, + .token.url, + .language-css .token.string, + .style .token.string { + color: #a5d6ff; + background: #161b22; + } + + .token.atrule, + .token.attr-value, + .token.keyword { + color: #a5d6ff; + } + + .token.function { + color: #d2a8ff; + } + + .token.regex, + .token.important, + .token.variable { + color: #a8daff; + } + + .token.important, + .token.bold { + font-weight: bold; + } + + .token.italic { + font-style: italic; + } + + .token.entity { + cursor: help; + } +} \ No newline at end of file diff --git a/docs/source/_static/prism.css b/docs/source/_static/prism.css new file mode 100644 index 0000000000..088a96cb6c --- /dev/null +++ b/docs/source/_static/prism.css @@ -0,0 +1,152 @@ +/** + * Github Light theme for Prism.js + * Based on Github: https://github.com + * @author Katorly + */ +/* General */ +pre[class*="language-"], +code[class*="language-"] { + color: #24292f; + font-size: 13px; + text-shadow: none; + font-family: Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace; + direction: ltr; + text-align: left; + white-space: pre; + word-spacing: normal; + word-break: normal; + line-height: 1.5; + -moz-tab-size: 4; + -o-tab-size: 4; + tab-size: 4; + -webkit-hyphens: none; + -moz-hyphens: none; + -ms-hyphens: none; + hyphens: none; +} + +pre[class*="language-"]::selection, +code[class*="language-"]::selection, +pre[class*="language-"]::mozselection, +code[class*="language-"]::mozselection { + text-shadow: none; + background: #9fc6e9; +} + +@media print { + + pre[class*="language-"], + code[class*="language-"] { + text-shadow: none; + } +} + +pre[class*="language-"] { + padding: 1em; + margin: .5em 0; + overflow: auto; + background: #f6f8fa; +} + +:not(pre)>code[class*="language-"] { + padding: .1em .3em; + border-radius: .3em; + color: #24292f; + background: #eff1f3; +} + +/* Line highlighting */ +pre[data-line] { + position: relative; +} + +pre[class*="language-"]>code[class*="language-"] { + position: relative; + z-index: 1; +} + +.line-highlight { + position: absolute; + left: 0; + right: 0; + padding: inherit 0; + margin-top: 1em; + background: #fff8c5; + box-shadow: inset 5px 0 0 #eed888; + z-index: 0; + pointer-events: none; + line-height: inherit; + white-space: pre; +} + +/* Tokens */ +.namespace { + opacity: .7; +} + +.token.comment, +.token.prolog, +.token.doctype, +.token.cdata { + color: #6e7781; +} + +.token.punctuation { + color: #24292f; +} + +.token.property, +.token.tag, +.token.boolean, +.token.number, +.token.constant, +.token.symbol, +.token.deleted { + color: #0550ae; +} + +.token.selector, +.token.attr-name, +.token.string, +.token.char, +.token.builtin, +.token.inserted { + color: #0a3069; +} + +.token.operator, +.token.entity, +.token.url, +.language-css .token.string, +.style .token.string { + color: #0550ae; +} + +.token.atrule, +.token.attr-value, +.token.keyword { + color: #cf222e; +} + +.token.function { + color: #8250df; +} + +.token.regex, +.token.important, +.token.variable { + color: #0a3069; +} + +.token.important, +.token.bold { + font-weight: bold; +} + +.token.italic { + font-style: italic; +} + +.token.entity { + cursor: help; +} \ No newline at end of file diff --git a/docs/source/_static/prism.js b/docs/source/_static/prism.js new file mode 100644 index 0000000000..fa92d07899 --- /dev/null +++ b/docs/source/_static/prism.js @@ -0,0 +1,7 @@ +/* PrismJS 1.30.0 +https://prismjs.com/download#themes=prism&languages=json+lua+yaml&plugins=toolbar */ +var _self="undefined"!=typeof window?window:"undefined"!=typeof WorkerGlobalScope&&self instanceof WorkerGlobalScope?self:{},Prism=function(e){var n=/(?:^|\s)lang(?:uage)?-([\w-]+)(?=\s|$)/i,t=0,r={},a={manual:e.Prism&&e.Prism.manual,disableWorkerMessageHandler:e.Prism&&e.Prism.disableWorkerMessageHandler,util:{encode:function e(n){return n instanceof i?new i(n.type,e(n.content),n.alias):Array.isArray(n)?n.map(e):n.replace(/&/g,"&").replace(/=g.reach);A+=w.value.length,w=w.next){var P=w.value;if(n.length>e.length)return;if(!(P instanceof i)){var E,S=1;if(y){if(!(E=l(b,A,e,m))||E.index>=e.length)break;var L=E.index,O=E.index+E[0].length,C=A;for(C+=w.value.length;L>=C;)C+=(w=w.next).value.length;if(A=C-=w.value.length,w.value instanceof i)continue;for(var j=w;j!==n.tail&&(Cg.reach&&(g.reach=W);var I=w.prev;if(_&&(I=u(n,I,_),A+=_.length),c(n,I,S),w=u(n,I,new i(f,p?a.tokenize(N,p):N,k,N)),M&&u(n,w,M),S>1){var T={cause:f+","+d,reach:W};o(e,n,t,w.prev,A,T),g&&T.reach>g.reach&&(g.reach=T.reach)}}}}}}function s(){var e={value:null,prev:null,next:null},n={value:null,prev:e,next:null};e.next=n,this.head=e,this.tail=n,this.length=0}function u(e,n,t){var r=n.next,a={value:t,prev:n,next:r};return n.next=a,r.prev=a,e.length++,a}function c(e,n,t){for(var r=n.next,a=0;a"+i.content+""},!e.document)return e.addEventListener?(a.disableWorkerMessageHandler||e.addEventListener("message",(function(n){var t=JSON.parse(n.data),r=t.language,i=t.code,l=t.immediateClose;e.postMessage(a.highlight(i,a.languages[r],r)),l&&e.close()}),!1),a):a;var g=a.util.currentScript();function f(){a.manual||a.highlightAll()}if(g&&(a.filename=g.src,g.hasAttribute("data-manual")&&(a.manual=!0)),!a.manual){var h=document.readyState;"loading"===h||"interactive"===h&&g&&g.defer?document.addEventListener("DOMContentLoaded",f):window.requestAnimationFrame?window.requestAnimationFrame(f):window.setTimeout(f,16)}return a}(_self);"undefined"!=typeof module&&module.exports&&(module.exports=Prism),"undefined"!=typeof global&&(global.Prism=Prism); +Prism.languages.json={property:{pattern:/(^|[^\\])"(?:\\.|[^\\"\r\n])*"(?=\s*:)/,lookbehind:!0,greedy:!0},string:{pattern:/(^|[^\\])"(?:\\.|[^\\"\r\n])*"(?!\s*:)/,lookbehind:!0,greedy:!0},comment:{pattern:/\/\/.*|\/\*[\s\S]*?(?:\*\/|$)/,greedy:!0},number:/-?\b\d+(?:\.\d+)?(?:e[+-]?\d+)?\b/i,punctuation:/[{}[\],]/,operator:/:/,boolean:/\b(?:false|true)\b/,null:{pattern:/\bnull\b/,alias:"keyword"}},Prism.languages.webmanifest=Prism.languages.json; +Prism.languages.lua={comment:/^#!.+|--(?:\[(=*)\[[\s\S]*?\]\1\]|.*)/m,string:{pattern:/(["'])(?:(?!\1)[^\\\r\n]|\\z(?:\r\n|\s)|\\(?:\r\n|[^z]))*\1|\[(=*)\[[\s\S]*?\]\2\]/,greedy:!0},number:/\b0x[a-f\d]+(?:\.[a-f\d]*)?(?:p[+-]?\d+)?\b|\b\d+(?:\.\B|(?:\.\d*)?(?:e[+-]?\d+)?\b)|\B\.\d+(?:e[+-]?\d+)?\b/i,keyword:/\b(?:and|break|do|else|elseif|end|false|for|function|goto|if|in|local|nil|not|or|repeat|return|then|true|until|while)\b/,function:/(?!\d)\w+(?=\s*(?:[({]))/,operator:[/[-+*%^&|#]|\/\/?|<[<=]?|>[>=]?|[=~]=?/,{pattern:/(^|[^.])\.\.(?!\.)/,lookbehind:!0}],punctuation:/[\[\](){},;]|\.+|:+/}; +!function(e){var n=/[*&][^\s[\]{},]+/,r=/!(?:<[\w\-%#;/?:@&=+$,.!~*'()[\]]+>|(?:[a-zA-Z\d-]*!)?[\w\-%#;/?:@&=+$.~*'()]+)?/,t="(?:"+r.source+"(?:[ \t]+"+n.source+")?|"+n.source+"(?:[ \t]+"+r.source+")?)",a="(?:[^\\s\\x00-\\x08\\x0e-\\x1f!\"#%&'*,\\-:>?@[\\]`{|}\\x7f-\\x84\\x86-\\x9f\\ud800-\\udfff\\ufffe\\uffff]|[?:-])(?:[ \t]*(?:(?![#:])|:))*".replace(//g,(function(){return"[^\\s\\x00-\\x08\\x0e-\\x1f,[\\]{}\\x7f-\\x84\\x86-\\x9f\\ud800-\\udfff\\ufffe\\uffff]"})),d="\"(?:[^\"\\\\\r\n]|\\\\.)*\"|'(?:[^'\\\\\r\n]|\\\\.)*'";function o(e,n){n=(n||"").replace(/m/g,"")+"m";var r="([:\\-,[{]\\s*(?:\\s<>[ \t]+)?)(?:<>)(?=[ \t]*(?:$|,|\\]|\\}|(?:[\r\n]\\s*)?#))".replace(/<>/g,(function(){return t})).replace(/<>/g,(function(){return e}));return RegExp(r,n)}e.languages.yaml={scalar:{pattern:RegExp("([\\-:]\\s*(?:\\s<>[ \t]+)?[|>])[ \t]*(?:((?:\r?\n|\r)[ \t]+)\\S[^\r\n]*(?:\\2[^\r\n]+)*)".replace(/<>/g,(function(){return t}))),lookbehind:!0,alias:"string"},comment:/#.*/,key:{pattern:RegExp("((?:^|[:\\-,[{\r\n?])[ \t]*(?:<>[ \t]+)?)<>(?=\\s*:\\s)".replace(/<>/g,(function(){return t})).replace(/<>/g,(function(){return"(?:"+a+"|"+d+")"}))),lookbehind:!0,greedy:!0,alias:"atrule"},directive:{pattern:/(^[ \t]*)%.+/m,lookbehind:!0,alias:"important"},datetime:{pattern:o("\\d{4}-\\d\\d?-\\d\\d?(?:[tT]|[ \t]+)\\d\\d?:\\d{2}:\\d{2}(?:\\.\\d*)?(?:[ \t]*(?:Z|[-+]\\d\\d?(?::\\d{2})?))?|\\d{4}-\\d{2}-\\d{2}|\\d\\d?:\\d{2}(?::\\d{2}(?:\\.\\d*)?)?"),lookbehind:!0,alias:"number"},boolean:{pattern:o("false|true","i"),lookbehind:!0,alias:"important"},null:{pattern:o("null|~","i"),lookbehind:!0,alias:"important"},string:{pattern:o(d),lookbehind:!0,greedy:!0},number:{pattern:o("[+-]?(?:0x[\\da-f]+|0o[0-7]+|(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:e[+-]?\\d+)?|\\.inf|\\.nan)","i"),lookbehind:!0},tag:r,important:n,punctuation:/---|[:[\]{}\-,|>?]|\.\.\./},e.languages.yml=e.languages.yaml}(Prism); +!function(){if("undefined"!=typeof Prism&&"undefined"!=typeof document){var e=[],t={},n=function(){};Prism.plugins.toolbar={};var a=Prism.plugins.toolbar.registerButton=function(n,a){var r;r="function"==typeof a?a:function(e){var t;return"function"==typeof a.onClick?((t=document.createElement("button")).type="button",t.addEventListener("click",(function(){a.onClick.call(this,e)}))):"string"==typeof a.url?(t=document.createElement("a")).href=a.url:t=document.createElement("span"),a.className&&t.classList.add(a.className),t.textContent=a.text,t},n in t?console.warn('There is a button with the key "'+n+'" registered already.'):e.push(t[n]=r)},r=Prism.plugins.toolbar.hook=function(a){var r=a.element.parentNode;if(r&&/pre/i.test(r.nodeName)&&!r.parentNode.classList.contains("code-toolbar")){var o=document.createElement("div");o.classList.add("code-toolbar"),r.parentNode.insertBefore(o,r),o.appendChild(r);var i=document.createElement("div");i.classList.add("toolbar");var l=e,d=function(e){for(;e;){var t=e.getAttribute("data-toolbar-order");if(null!=t)return(t=t.trim()).length?t.split(/\s*,\s*/g):[];e=e.parentElement}}(a.element);d&&(l=d.map((function(e){return t[e]||n}))),l.forEach((function(e){var t=e(a);if(t){var n=document.createElement("div");n.classList.add("toolbar-item"),n.appendChild(t),i.appendChild(n)}})),o.appendChild(i)}};a("label",(function(e){var t=e.element.parentNode;if(t&&/pre/i.test(t.nodeName)&&t.hasAttribute("data-label")){var n,a,r=t.getAttribute("data-label");try{a=document.querySelector("template#"+r)}catch(e){}return a?n=a.content:(t.hasAttribute("data-url")?(n=document.createElement("a")).href=t.getAttribute("data-url"):n=document.createElement("span"),n.textContent=r),n}})),Prism.hooks.add("complete",r)}}(); diff --git a/docs/source/_static/theme-override.css b/docs/source/_static/theme-override.css new file mode 100644 index 0000000000..e41ab2c2d6 --- /dev/null +++ b/docs/source/_static/theme-override.css @@ -0,0 +1,140 @@ +:root { + --link: #4a90e2; + --link-hover: #1c6cd9; + + --readthedocs-search-color: hsl(var(--foreground)); + --readthedocs-search-link-color: var(--link); + --readthedocs-search-content-background-color: hsl(var(--background)); + --readthedocs-search-content-border-color: hsl(var(--border)); + --readthedocs-search-footer-background-color: hsl(var(--background)); + --readthedocs-search-footer-color: hsl(var(--foreground)); + --readthedocs-search-footer-code-background-color: hsl(var(--background)); + --readthedocs-search-footer-code-border-color: hsl(var(--background)); + --readthedocs-search-input-background-color: hsl(var(--accent)); + --readthedocs-search-result-color: hsl(var(--foreground)); + --readthedocs-search-result-icon-color: hsl(var(--foreground)); + --readthedocs-search-result-heading-color: hsl(var(--foreground)); + --readthedocs-search-result-subheading-color: hsl(var(--foreground)); + --readthedocs-search-result-active-background-color: hsl(var(--accent)); + --readthedocs-search-result-border-color: hsl(var(--border)); + + --readthedocs-flyout-background-color: hsl(var(--background)); + --readthedocs-flyout-color: hsl(var(--foreground)); + --readthedocs-flyout-current-version-color: hsl(var(--foreground)); + --readthedocs-flyout-item-link-color: var(--link); + --readthedocs-flyout-link-color: var(--link); + --readthedocs-flyout-section-heading-color: hsl(var(--foreground)); +} + +/* Less aggressive dark background */ +@media (prefers-color-scheme: dark) { + :root { + --background: 220 14% 9% !important; + --border: 216 14% 17%; + --accent: 216 14% 17%; + --input: 216 14% 17%; + --muted: 223 27% 14%; + --card: 220 14% 9%; + + --link: #ffffff; + --link-hover: #ffffff; + } + + .contents ul li a.reference:hover, .sd-dropdown .toctree-wrapper ul li a.reference, details.sd-dropdown .sd-summary-title { + --muted-foreground: 215.4 16.3% 86.9%; + } +} + +/* Enable hover-to-highlight in TOC */ +.contents ul li a.reference:hover, .toctree-wrapper ul li a.reference:hover { + text-decoration: underline !important; +} + +/* Hide text underline in tables since the underlines clash with table lines */ +#content a.sd-badge:not(.toc-backref), #content table a:not(.toc-backref) { + text-decoration: none; +} + +/* Override link colors, default is foreground */ +#content a:not(.toc-backref) { + color: var(--link); + font-weight: 600; +} + +#content a:not(.toc-backref):hover, #content a:not(.toc-backref):focus { + color: var(--link-hover); +} + +#content .highlight { + background-color: #f6f8fa !important; + border-radius: 0.25rem; + font-variant-ligatures: none; +} + +@media (prefers-color-scheme: dark) { + #content .highlight { + background-color: #161b22 !important; + } +} + +/* Disables the saturation filter on project icon in dark mode */ +.dark\:invert { + --tw-invert: none !important; +} + +/* Disable no-wrap set on some code blocks, causing x-overflow issues in right bar */ +code { + white-space: normal; +} + +/* Hide the keybind shortcut for search, we haven't linked this to sphinx search addon yet */ +#searchbox kbd { + display: none !important; +} + +#search-input { + padding-right: 12px !important; +} + +/* Table headers are bolded in dark mode, do it in light mode too */ +table th { + font-weight: 600 !important; +} + +/* Highlight non-header rows on hover */ +tbody tr:hover { + background-color: hsl(var(--muted)); +} + +/* Increase maximum width for docs, default is quite narrow at 1400px max */ +@media (min-width: 1400px) { + .container { + max-width: 2000px !important; + } +} + +/* Less intrusive scrollbar in the TOC */ +#left-sidebar::-webkit-scrollbar, #right-sidebar .sticky::-webkit-scrollbar { + width: 6px; + border-radius: 0; +} + +#left-sidebar::-webkit-scrollbar-thumb, #right-sidebar .sticky::-webkit-scrollbar-thumb { + background-color: hsl(var(--border));; + border-radius: 0; +} + +#left-sidebar::-webkit-scrollbar-thumb:hover, #right-sidebar .sticky::-webkit-scrollbar-thumb:hover { + background-color: hsl(var(--muted));; +} + +@media (min-width: 1024px) { + .container:has(#left-sidebar) { + grid-template-columns: 310px minmax(0, 1fr); + } +} + +/* Always enable scrollbar in left TOC to prevent layout shifts when expanding */ +#left-sidebar { + overflow-y: scroll; +} diff --git a/docs/source/conf.py b/docs/source/conf.py index fbce7975da..aaa42e3678 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,11 +16,16 @@ import os import sys import subprocess +from dataclasses import asdict +from sphinxawesome_theme import ThemeOptions +from sphinxawesome_theme.postprocess import Icons + # 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. project_root = os.path.abspath('../../') sys.path.insert(0, project_root) +sys.path.append(os.path.abspath("_ext")) # -- General configuration ------------------------------------------------ @@ -37,6 +42,8 @@ extensions = [ 'sphinx.ext.coverage', 'sphinx.ext.viewcode', 'sphinx.ext.autosectionlabel', + 'sphinx_design', + 'omw-directives' ] #autosectionlabel_prefix_document = True @@ -91,7 +98,14 @@ except Exception as ex: rst_prolog = f""" .. |luaApiRevision| replace:: {luaApiRevision} +.. |luaApiRevisionBadge| replace:: :bdg-link-info-line:`API v{luaApiRevision} ` + .. |ppApiRevision| replace:: {ppApiRevision} +.. |bdg-ctx-menu| replace:: :bdg-warning:`menu` +.. |bdg-ctx-global| replace:: :bdg-danger:`global` +.. |bdg-ctx-player| replace:: :bdg-secondary:`player` +.. |bdg-ctx-local| replace:: :bdg-info:`local` +.. |bdg-ctx-all| replace:: :bdg-danger:`global` :bdg-warning:`menu` :bdg-info:`local` """ # The language for content autogenerated by Sphinx. Refer to documentation @@ -125,6 +139,7 @@ exclude_patterns = [] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +pygments_style_dark = 'github-dark' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] @@ -138,22 +153,39 @@ primary_domain = 'c' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_rtd_theme' +html_theme = 'sphinxawesome_theme' # 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 = { - 'navigation_with_keys': True, - 'flyout_display': 'attached', -} +html_theme_options = asdict(ThemeOptions( + show_breadcrumbs=False, + main_nav_links= { + "Modding": "reference/modding/index", + "Lua API": "reference/lua-scripting/overview", + "Post-Processing": "reference/postprocessing/index", + }, + show_scrolltop=False, # Useful, but hard to position with the Flyout addon since the best place for that is bottom right +)) + +html_permalinks_icon = Icons.permalinks_icon + +html_js_files = [ + 'prism.js' +] + +html_css_files = [ + "theme-override.css", + "luadoc.css", + "figures.css", + "prism.css", + "prism-dark.css", +] # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] def setup(app): - app.add_css_file('figures.css') - app.add_css_file('luadoc.css') try: subprocess.call(['bash', project_root + '/docs/source/generate_luadoc.sh']) except Exception as e: @@ -161,19 +193,19 @@ def setup(app): # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". -#html_title = None +html_title = 'OpenMW' # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = 'OpenMW Documentation' +# html_short_title = 'OpenMW Documentation' # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/openmw.png' +html_logo = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/openmw.png' # 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 = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/favicon.png' +html_favicon = 'https://gitlab.com/OpenMW/openmw-docs/raw/master/docs/source/_static/images/favicon.png' # 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, diff --git a/docs/source/index.rst b/docs/source/index.rst index de3773ddbd..6906403e9d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,9 +1,34 @@ Welcome to OpenMW's Documentation! ================================== -.. toctree:: - :caption: Table of Contents - :maxdepth: 3 +This documentation covers all aspects of OpenMW development, scripting, and content creation. +Use the categorized sections below to quickly access technical references, modding tools, and installation guides. - manuals/index - reference/index +.. dropdown:: Table of Contents + :icon: book + + .. toctree:: + :caption: Reference + :titlesonly: + :maxdepth: 4 + + reference/modding/index + reference/postprocessing/index + + .. toctree:: + :caption: Lua + :titlesonly: + :maxdepth: 4 + + reference/lua-scripting/overview + reference/lua-scripting/api + reference/lua-scripting/teal + + .. toctree:: + :caption: Help + :titlesonly: + :maxdepth: 4 + + manuals/installation/index + manuals/openmw-cs/index + manuals/documentationHowTo diff --git a/docs/source/install_luadocumentor_in_docker.sh b/docs/source/install_luadocumentor_in_docker.sh index 5d37a37351..388ba8b739 100755 --- a/docs/source/install_luadocumentor_in_docker.sh +++ b/docs/source/install_luadocumentor_in_docker.sh @@ -33,7 +33,7 @@ PATH=$PATH:~/luarocks/bin echo "Install openmwluadocumentor" git clone https://gitlab.com/ptmikheev/openmw-luadocumentor.git cd openmw-luadocumentor -git checkout 78577b255d19a1f4f4f539662e00357936b73c33 +git checkout 122e4f55c5f2dd62076135211e03edfb8dec3a55 luarocks make luarocks/openmwluadocumentor-0.2.0-1.rockspec cd ~ rm -r openmw-luadocumentor diff --git a/docs/source/reference/documentationHowTo.rst b/docs/source/manuals/documentationHowTo.rst similarity index 99% rename from docs/source/reference/documentationHowTo.rst rename to docs/source/manuals/documentationHowTo.rst index d2b67d02ca..fb1062cd19 100644 --- a/docs/source/reference/documentationHowTo.rst +++ b/docs/source/manuals/documentationHowTo.rst @@ -1,6 +1,6 @@ -####################################### -So you want to help with documentation? -####################################### +############### +Help with docs? +############### Or a beginner's guide to writing docs without having to deal with more techie stuff than you have to. ##################################################################################################### diff --git a/docs/source/manuals/index.rst b/docs/source/manuals/index.rst deleted file mode 100644 index e6f0cbef2e..0000000000 --- a/docs/source/manuals/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -User Manuals -============ - -.. toctree:: - :maxdepth: 2 - - openmw-cs/index - installation/index diff --git a/docs/source/manuals/installation/index.rst b/docs/source/manuals/installation/index.rst index 6e6f5034ef..c1113603dc 100644 --- a/docs/source/manuals/installation/index.rst +++ b/docs/source/manuals/installation/index.rst @@ -4,9 +4,12 @@ Installation Guide In order to use OpenMW, you must install both the engine and the game files for a compatible game. -.. toctree:: - :maxdepth: 2 +.. dropdown:: Table of Contents + :icon: book - install-openmw - install-game-files - common-problems \ No newline at end of file + .. toctree:: + :maxdepth: 2 + + install-openmw + install-game-files + common-problems diff --git a/docs/source/manuals/installation/install-game-files.rst b/docs/source/manuals/installation/install-game-files.rst index 42d4eb8d78..cb44f7d1de 100644 --- a/docs/source/manuals/installation/install-game-files.rst +++ b/docs/source/manuals/installation/install-game-files.rst @@ -163,7 +163,10 @@ Debian/Ubuntu - using "Steam Proton" & "OpenMW launcher". #. Launch "OpenMW launcher" and follow the setup wizard, when asked, point it at the location you installed Morrowind to, we will be looking for the directory that contains the Morrowing.esm file, for example '/steam library/steamapps/common/Morrowind/Data Files/'. #. Everything should now be in place, click that big "PLAY" button and fire up OpenMW. -Note, Bloodmoon.esm needs to be below Tribunal.esm in your datafiles list, if you don't have the right order a red "!" will apear next to the filename in the datafiles section of the OpenMW launcher, just drag bloodmoon below tribunal to fix it. +.. note:: + `Bloodmoon.esm` needs to be below `Tribunal.esm` in your data files list. + If you don't have the right order a red `!` will apear next to the filename in the data files section of the OpenMW launcher. + To fix, drag `Bloodmoon.esm` below `Tribunal.esm`. Wine ~~~~ diff --git a/docs/source/manuals/installation/install-openmw.rst b/docs/source/manuals/installation/install-openmw.rst index 2ef72abfd5..c99b04da91 100644 --- a/docs/source/manuals/installation/install-openmw.rst +++ b/docs/source/manuals/installation/install-openmw.rst @@ -2,53 +2,59 @@ Install OpenMW ============== -The (easier) Binary Way -======================= +Direct Download +=============== If you're not sure what any of the different methods mean, you should probably stick to this one. Simply download the latest version for your operating system from `github.com/OpenMW/openmw/releases `_ and run the install package once downloaded. It's now installed! - .. note:: - There is no need to uninstall previous versions - as OpenMW automatically installs into a separate directory for each new version. - Your saves and configuration are compatible and accessible between versions. +.. note:: + There is no need to uninstall previous versions + as OpenMW automatically installs into a separate directory for each new version. + Your saves and configuration are compatible and accessible between versions. -The (bleeding edge) Source Way -============================== +From Source +=========== Visit the `Development Environment Setup `_ section of the Wiki for detailed instructions on how to build the engine. -The Ubuntu Way -============== +Ubuntu +====== A `Launchpad PPA `_ is available. -Add it and install OpenMW:: +Add it and install OpenMW. + +.. code-block:: console $ sudo add-apt-repository ppa:openmw/openmw $ sudo apt update $ sudo apt install openmw -The Arch Linux Way -================== +Arch Linux +========== The binary package is available in the official [community] Repositories. -To install, simply run the following as root (or in sudo):: +To install, simply run the following as root (or in sudo). - # pacman -S openmw +.. code-block:: console -The Void Linux Way -================== + $ pacman -S openmw + +Void Linux +========== The binary package is available in the official Repository -To install simply run the following as root (or in sudo):: +To install simply run the following as root (or in sudo). - # xbps-install openmw +.. code-block:: console -The Debian Way -============== + $ xbps-install openmw + +Debian +====== OpenMW is available from the unstable (sid) repository of Debian contrib and can be easily installed if you are using testing or unstable. @@ -56,10 +62,11 @@ However, it depends on several packages which are not in stable, so it is not possible to install OpenMW in Wheezy without creating a FrankenDebian. This is not recommended or supported. -The Flatpak Way -=============== +Flatpak +======= OpenMW is available as a flatpak. With flatpak installed, run the command below. It should show up on your desktop. -:: - # flatpak install openmw +.. code-block:: console + + $ flatpak install openmw diff --git a/docs/source/manuals/openmw-cs/index.rst b/docs/source/manuals/openmw-cs/index.rst index f1f51409d4..637f5858b2 100644 --- a/docs/source/manuals/openmw-cs/index.rst +++ b/docs/source/manuals/openmw-cs/index.rst @@ -1,33 +1,35 @@ -OpenMW CS User Manual +OpenMW-CS User Manual ##################### -The following document is the complete user manual for *OpenMW CS*, the +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 + 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 intended. Please report any software problems as bugs in the software, not errors in the manual. -.. toctree:: - :caption: Table of Contents - :maxdepth: 2 +.. dropdown:: Table of Contents + :icon: book - foreword - tour - files-and-directories - starting-dialog - tables - tables-file - tables-world - tables-mechanics - tables-characters - tables-assets - record-types - record-filters - cell-view - records-drag-and-drop + .. toctree:: + :maxdepth: 2 + + foreword + tour + files-and-directories + starting-dialog + tables + tables-file + tables-world + tables-mechanics + tables-characters + tables-assets + record-types + record-filters + cell-view + records-drag-and-drop diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst deleted file mode 100644 index 9aa409f784..0000000000 --- a/docs/source/reference/index.rst +++ /dev/null @@ -1,11 +0,0 @@ -################## -Reference Material -################## - -.. toctree:: - :maxdepth: 2 - - modding/index - lua-scripting/index - postprocessing/index - documentationHowTo diff --git a/docs/source/reference/lua-scripting/ai/combat.rst b/docs/source/reference/lua-scripting/ai/combat.rst new file mode 100644 index 0000000000..06dd9c1452 --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/combat.rst @@ -0,0 +1,36 @@ +Combat +====== + +.. include:: ../version.rst + +Attack another actor. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - cancelOther + - boolean [default=true] + - whether to cancel all other AI packages + * - target + - `GameObject <../openmw_core.html##(GameObject)>`_ [required] + - the actor to attack + +**Examples** + +.. code-block:: Lua + + -- from local script add package to self + local AI = require('openmw.interfaces').AI + AI.startPackage({type='Combat', target=anotherActor}) + + -- via event to any actor + actor:sendEvent('StartAIPackage', {type='Combat', target=anotherActor}) diff --git a/docs/source/reference/lua-scripting/ai/escort.rst b/docs/source/reference/lua-scripting/ai/escort.rst new file mode 100644 index 0000000000..fd9f2d05e5 --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/escort.rst @@ -0,0 +1,49 @@ +Escort +====== + +.. include:: ../version.rst + +Escort another actor to the given location. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - cancelOther + - boolean [default=true] + - whether to cancel all other AI packages + * - target + - `GameObject <../openmw_core.html##(GameObject)>`_ [required] + - the actor to follow + * - destPosition + - `3d vector <../openmw_util.html##(Vector3)>`_ [required] + - the destination point + * - destCell + - Cell [optional] + - the destination cell + * - duration + - number [optional] + - duration in game time (will be rounded up to the next hour) + * - isRepeat + - boolean [optional] + - Will the package repeat (true or false) + +**Example** + +.. code-block:: Lua + + actor:sendEvent('StartAIPackage', { + type = 'Escort', + target = object.self, + destPosition = util.vector3(x, y, z), + duration = 3 * time.hour, + isRepeat = true + }) diff --git a/docs/source/reference/lua-scripting/ai/follow.rst b/docs/source/reference/lua-scripting/ai/follow.rst new file mode 100644 index 0000000000..ac6b70bcf7 --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/follow.rst @@ -0,0 +1,37 @@ +Follow +====== + +.. include:: ../version.rst + +Follow another actor. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - cancelOther + - boolean [default=true] + - whether to cancel all other AI packages + * - target + - `GameObject <../openmw_core.html##(GameObject)>`_ [required] + - the actor to follow + * - destCell + - Cell [optional] + - the destination cell + * - duration + - number [optional] + - duration in game time (will be rounded up to the next hour) + * - destPosition + - `3d vector <../openmw_util.html##(Vector3)>`_ [optional] + - the destination point + * - isRepeat + - boolean [optional] + - Will the package repeat (true or false) diff --git a/docs/source/reference/lua-scripting/ai/pursue.rst b/docs/source/reference/lua-scripting/ai/pursue.rst new file mode 100644 index 0000000000..08385c57ae --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/pursue.rst @@ -0,0 +1,25 @@ +Pursue +====== + +.. include:: ../version.rst + +Pursue another actor. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - cancelOther + - boolean [default=true] + - whether to cancel all other AI packages + * - target + - `GameObject <../openmw_core.html##(GameObject)>`_ [required] + - the actor to pursue diff --git a/docs/source/reference/lua-scripting/ai/travel.rst b/docs/source/reference/lua-scripting/ai/travel.rst new file mode 100644 index 0000000000..06a47c868d --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/travel.rst @@ -0,0 +1,28 @@ +Travel +====== + +.. include:: ../version.rst + +Go to given location. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - cancelOther + - boolean [default=true] + - whether to cancel all other AI packages + * - destPosition + - `3d vector <../openmw_util.html##(Vector3)>`_ [required] + - the point to travel to + * - isRepeat + - boolean [optional] + - Will the package repeat (true or false) diff --git a/docs/source/reference/lua-scripting/ai/wander.rst b/docs/source/reference/lua-scripting/ai/wander.rst new file mode 100644 index 0000000000..fc702f12e2 --- /dev/null +++ b/docs/source/reference/lua-scripting/ai/wander.rst @@ -0,0 +1,53 @@ +Wander +====== + +.. include:: ../version.rst + +Wander nearby current position. + +**Arguments** + +.. list-table:: + :header-rows: 1 + :widths: 20 20 60 + + * - name + - type + - description + * - type + - string [required] + - the name of the package (see packages listed below) + * - distance + - float [default=0] + - the actor to follow + * - duration + - number [optional] + - duration in game time (will be rounded up to the next hour) + * - idle + - table [optional] + - Idle chance values, up to 8 + * - isRepeat + - boolean [optional] + - Will the package repeat (true or false) + +**Example** + +.. code-block:: Lua + + local idleTable = { + idle2 = 60, + idle3 = 50, + idle4 = 40, + idle5 = 30, + idle6 = 20, + idle7 = 10, + idle8 = 0, + idle9 = 25 + } + actor:sendEvent('StartAIPackage', { + type = 'Wander', + distance = 5000, + duration = 5 * time.hour, + idle = idleTable, + isRepeat = true + }) diff --git a/docs/source/reference/lua-scripting/aipackages.rst b/docs/source/reference/lua-scripting/aipackages.rst deleted file mode 100644 index 7a23d156f5..0000000000 --- a/docs/source/reference/lua-scripting/aipackages.rst +++ /dev/null @@ -1,225 +0,0 @@ -Built-in AI packages -==================== - -.. include:: version.rst - -Starting an AI package ----------------------- - -There are two ways to start AI package: - -.. code-block:: Lua - - -- from local script add package to self - local AI = require('openmw.interfaces').AI - AI.startPackage(options) - - -- via event to any actor - actor:sendEvent('StartAIPackage', options) - -``options`` is Lua table with arguments of the AI package. - -**Common arguments that can be used with any AI package** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - type - - string [required] - - the name of the package (see packages listed below) - * - cancelOther - - boolean [default=true] - - whether to cancel all other AI packages - -Combat ------- - -Attack another actor. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - target - - `GameObject `_ [required] - - the actor to attack - -**Examples** - -.. code-block:: Lua - - -- from local script add package to self - local AI = require('openmw.interfaces').AI - AI.startPackage({type='Combat', target=anotherActor}) - - -- via event to any actor - actor:sendEvent('StartAIPackage', {type='Combat', target=anotherActor}) - -Pursue ------- - -Pursue another actor. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - target - - `GameObject `_ [required] - - the actor to pursue - -Follow ------- - -Follow another actor. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - target - - `GameObject `_ [required] - - the actor to follow - * - destCell - - Cell [optional] - - the destination cell - * - duration - - number [optional] - - duration in game time (will be rounded up to the next hour) - * - destPosition - - `3d vector `_ [optional] - - the destination point - * - isRepeat - - boolean [optional] - - Will the package repeat (true or false) - -Escort ------- - -Escort another actor to the given location. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - target - - `GameObject `_ [required] - - the actor to follow - * - destPosition - - `3d vector `_ [required] - - the destination point - * - destCell - - Cell [optional] - - the destination cell - * - duration - - number [optional] - - duration in game time (will be rounded up to the next hour) - * - isRepeat - - boolean [optional] - - Will the package repeat (true or false) - -**Example** - -.. code-block:: Lua - - actor:sendEvent('StartAIPackage', { - type = 'Escort', - target = object.self, - destPosition = util.vector3(x, y, z), - duration = 3 * time.hour, - isRepeat = true - }) - -Wander ------- - -Wander nearby current position. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - distance - - float [default=0] - - the actor to follow - * - duration - - number [optional] - - duration in game time (will be rounded up to the next hour) - * - idle - - table [optional] - - Idle chance values, up to 8 - * - isRepeat - - boolean [optional] - - Will the package repeat (true or false) - -**Example** - -.. code-block:: Lua - - local idleTable = { - idle2 = 60, - idle3 = 50, - idle4 = 40, - idle5 = 30, - idle6 = 20, - idle7 = 10, - idle8 = 0, - idle9 = 25 - } - actor:sendEvent('StartAIPackage', { - type = 'Wander', - distance = 5000, - duration = 5 * time.hour, - idle = idleTable, - isRepeat = true - }) - -Travel ------- - -Go to given location. - -**Arguments** - -.. list-table:: - :header-rows: 1 - :widths: 20 20 60 - - * - name - - type - - description - * - destPosition - - `3d vector `_ [required] - - the point to travel to - * - isRepeat - - boolean [optional] - - Will the package repeat (true or false) diff --git a/docs/source/reference/lua-scripting/api.rst b/docs/source/reference/lua-scripting/api.rst index 82a860b355..b8920b7ff1 100644 --- a/docs/source/reference/lua-scripting/api.rst +++ b/docs/source/reference/lua-scripting/api.rst @@ -1,60 +1,21 @@ -################# -Lua API reference -################# +############# +API Reference +############# .. include:: version.rst .. toctree:: :hidden: - engine_handlers - user_interface - aipackages + index_packages + index_auxpackages + index_aipackages + index_interfaces + UI setting_renderers + Engine Handlers events - openmw_ambient - openmw_animation - openmw_async - openmw_camera - openmw_core - openmw_debug - openmw_input - openmw_markup - openmw_menu - openmw_nearby - openmw_postprocessing - openmw_self - openmw_storage - openmw_types - openmw_ui - openmw_util - openmw_vfs - openmw_world - openmw_aux_calendar - openmw_aux_time - openmw_aux_ui - openmw_aux_util - interface_activation - interface_ai - interface_animation - interface_camera - interface_controls - interface_gamepadcontrols - interface_item_usage - interface_mwui - interface_settings - interface_skill_progression - interface_ui - interface_crimes - iterables - - -- :ref:`Engine handlers reference` -- :ref:`User interface reference ` -- `Game object reference `_ -- `Cell reference `_ -- :ref:`Built-in AI packages` -- :ref:`Built-in events` + Iterables **API packages** @@ -66,7 +27,7 @@ Player scripts are local scripts that are attached to a player. .. include:: tables/packages.rst -**openmw_aux** +**Auxiliary packages** ``openmw_aux.*`` are built-in libraries that are itself implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient. Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended. diff --git a/docs/source/reference/lua-scripting/engine_handlers.rst b/docs/source/reference/lua-scripting/engine_handlers.rst index ac6979a236..29b14aee55 100644 --- a/docs/source/reference/lua-scripting/engine_handlers.rst +++ b/docs/source/reference/lua-scripting/engine_handlers.rst @@ -7,6 +7,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Can be defined by any script** +|bdg-ctx-all| + .. list-table:: :widths: 20 80 @@ -16,6 +18,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Can be defined by any non-menu script** +|bdg-ctx-global| |bdg-ctx-local| + .. list-table:: :widths: 20 80 @@ -39,6 +43,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Only for global scripts** +|bdg-ctx-global| + .. list-table:: :widths: 20 80 @@ -61,6 +67,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Only for local scripts** +|bdg-ctx-local| + .. list-table:: :widths: 20 80 @@ -86,6 +94,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Only menu scripts and local scripts attached to a player** +|bdg-ctx-menu| |bdg-ctx-player| + .. list-table:: :widths: 20 80 @@ -140,6 +150,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Only for local scripts attached to a player** +|bdg-ctx-player| + .. list-table:: :widths: 20 80 @@ -152,6 +164,8 @@ Engine handler is a function defined by a script, that can be called by the engi **Only for menu scripts** +|bdg-ctx-menu| + .. list-table:: :widths: 20 80 diff --git a/docs/source/reference/lua-scripting/events.rst b/docs/source/reference/lua-scripting/events.rst index 282e3d1173..007e0e43d1 100644 --- a/docs/source/reference/lua-scripting/events.rst +++ b/docs/source/reference/lua-scripting/events.rst @@ -1,5 +1,5 @@ -Built-in events -=============== +Events +====== .. include:: version.rst diff --git a/docs/source/reference/lua-scripting/index.rst b/docs/source/reference/lua-scripting/index.rst deleted file mode 100644 index f3764c4401..0000000000 --- a/docs/source/reference/lua-scripting/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -#################### -OpenMW Lua scripting -#################### - -.. note:: - OpenMW Lua is not compatible with MWSE. - -.. include:: version.rst - -.. toctree:: - :caption: Table of Contents - :includehidden: - :maxdepth: 2 - - overview - api - teal - diff --git a/docs/source/reference/lua-scripting/index_aipackages.rst b/docs/source/reference/lua-scripting/index_aipackages.rst new file mode 100644 index 0000000000..2b8b41bb08 --- /dev/null +++ b/docs/source/reference/lua-scripting/index_aipackages.rst @@ -0,0 +1,24 @@ +AI packages +============ + +.. include:: version.rst + +.. toctree:: + :hidden: + :glob: + + ai/* + +Starting an AI package +---------------------- + +There are two ways to start AI package: + +.. code-block:: Lua + + -- from local script add package to self + local AI = require('openmw.interfaces').AI + AI.startPackage(options) + + -- via event to any actor + actor:sendEvent('StartAIPackage', options) diff --git a/docs/source/reference/lua-scripting/index_auxpackages.rst b/docs/source/reference/lua-scripting/index_auxpackages.rst new file mode 100644 index 0000000000..ea17a3ddbb --- /dev/null +++ b/docs/source/reference/lua-scripting/index_auxpackages.rst @@ -0,0 +1,21 @@ +################## +Auxiliary Packages +################## + +.. include:: version.rst + +.. toctree:: + :hidden: + + calendar + time + ui + util + + +**Auxiliary packages** + +``openmw_aux.*`` are built-in libraries that are itself implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient. +Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended. + +.. include:: tables/aux_packages.rst diff --git a/docs/source/reference/lua-scripting/index_interfaces.rst b/docs/source/reference/lua-scripting/index_interfaces.rst new file mode 100644 index 0000000000..37a2df63c4 --- /dev/null +++ b/docs/source/reference/lua-scripting/index_interfaces.rst @@ -0,0 +1,25 @@ +########## +Interfaces +########## + +.. include:: version.rst + +.. toctree:: + :hidden: + + Activation + AI + AnimationController + Camera + Controls + Crimes + GamepadControls + ItemUsage + MWUI + Settings + SkillProgression + UI + +**Interfaces of built-in scripts** + +.. include:: tables/interfaces.rst diff --git a/docs/source/reference/lua-scripting/index_packages.rst b/docs/source/reference/lua-scripting/index_packages.rst new file mode 100644 index 0000000000..53a836519f --- /dev/null +++ b/docs/source/reference/lua-scripting/index_packages.rst @@ -0,0 +1,37 @@ +######## +Packages +######## + +.. include:: version.rst + +.. toctree:: + :hidden: + + ambient + animation + async + camera + core + debug + input + markup + menu + nearby + postprocessing + self + storage + types + ui + util + vfs + world + +**API packages** + +API packages provide functions that can be called by scripts. I.e. it is a script-to-engine interaction. +A package can be loaded with ``require('')``. +It can not be overloaded even if there is a lua file with the same name. +The list of available packages is different for global and for local scripts. +Player scripts are local scripts that are attached to a player. + +.. include:: tables/packages.rst diff --git a/docs/source/reference/lua-scripting/overview.rst b/docs/source/reference/lua-scripting/overview.rst index b889b09a9f..852d63ca0a 100644 --- a/docs/source/reference/lua-scripting/overview.rst +++ b/docs/source/reference/lua-scripting/overview.rst @@ -1,5 +1,5 @@ -Overview of Lua scripting -######################### +Overview +######## .. include:: version.rst @@ -384,8 +384,8 @@ Player scripts are local scripts that are attached to a player. .. include:: tables/packages.rst -openmw_aux ----------- +Auxiliary packages +------------------ ``openmw_aux.*`` are built-in libraries that are themselves implemented in Lua. They can not do anything that is not possible with the basic API, they only make it more convenient. Sources can be found in ``resources/vfs/openmw_aux``. In theory mods can override them, but it is not recommended. @@ -544,7 +544,7 @@ The protection mod attaches an additional local script to every actor. The scrip In order to be able to intercept the event, the protection script should be placed in the load order below the original script. -See :ref:`the list of events ` that are used by built-in scripts. +See :ref:`the list of events ` that are used by built-in scripts. Timers @@ -618,7 +618,7 @@ An example: } } -Also in `openmw_aux`_ is the helper function ``runRepeatedly``, it is implemented on top of unsavable timers: +Also in `Auxiliary packages`_ is the helper function ``runRepeatedly``, it is implemented on top of unsavable timers: .. code-block:: Lua @@ -641,7 +641,7 @@ Using IDE for Lua scripting Find the directory ``resources/lua_api`` in your installation of OpenMW. It describes OpenMW LuaAPI in `LDT Documentation Language `__. -It is the source from which the :ref:`API reference ` is generated. +It is the source from which the :ref:`API reference ` is generated. If you write scripts using `Lua Development Tools `__ (eclipse-based IDE), you can import these files to get code autocompletion and integrated OpenMW API reference. Here are the steps: diff --git a/docs/source/reference/lua-scripting/setting_renderers.rst b/docs/source/reference/lua-scripting/setting_renderers.rst index b85c7fbaab..f315615cb4 100644 --- a/docs/source/reference/lua-scripting/setting_renderers.rst +++ b/docs/source/reference/lua-scripting/setting_renderers.rst @@ -1,5 +1,5 @@ -Built-in Setting Renderers -========================== +Setting Renderers +================= .. include:: version.rst diff --git a/docs/source/reference/lua-scripting/tables/aux_packages.rst b/docs/source/reference/lua-scripting/tables/aux_packages.rst index d0217ce202..202f5219c2 100644 --- a/docs/source/reference/lua-scripting/tables/aux_packages.rst +++ b/docs/source/reference/lua-scripting/tables/aux_packages.rst @@ -1,12 +1,19 @@ -+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ -| Built-in library | Can be used | Description | -+=========================================================+====================+===============================================================+ -|:ref:`openmw_aux.calendar ` | everywhere | | Game time calendar | -+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw_aux.util ` | everywhere | | Miscellaneous utils | -+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw_aux.time ` | everywhere | | Timers and game time utils | -+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw_aux.ui ` | by player and menu | | User interface utils | -| | scripts | | -+---------------------------------------------------------+--------------------+---------------------------------------------------------------+ +.. list-table:: + :widths: 30 40 60 + :header-rows: 1 + + * - Module + - Context + - Description + * - :doc:`calendar ` + - |bdg-ctx-all| + - Game time calendar + * - :doc:`time ` + - |bdg-ctx-all| + - Timers and game time utils + * - :doc:`ui ` + - |bdg-ctx-menu| |bdg-ctx-player| + - User interface utils + * - :doc:`util ` + - |bdg-ctx-all| + - Miscellaneous utils diff --git a/docs/source/reference/lua-scripting/tables/interfaces.rst b/docs/source/reference/lua-scripting/tables/interfaces.rst index d8dfffe47d..8496d01029 100644 --- a/docs/source/reference/lua-scripting/tables/interfaces.rst +++ b/docs/source/reference/lua-scripting/tables/interfaces.rst @@ -1,48 +1,43 @@ .. list-table:: - :widths: 20 20 60 + :widths: 30 40 60 + :header-rows: 1 * - Interface - - Can be used + - Context - Description - * - :ref:`Activation ` - - by global scripts + * - :doc:`Activation ` + - |bdg-ctx-global| - Allows to extend or override built-in activation mechanics. - * - :ref:`AI ` - - by local scripts + * - :doc:`AI ` + - |bdg-ctx-local| - Control basic AI of NPCs and creatures. - * - :ref:`AnimationController ` - - by local scripts + * - :doc:`AnimationController ` + - |bdg-ctx-local| - Control animations of NPCs and creatures. - * - :ref:`Camera ` - - by player scripts - - | Allows to alter behavior of the built-in camera script - | without overriding the script completely. - * - :ref:`Controls ` - - by player scripts - - | Allows to alter behavior of the built-in script - | that handles player controls. - * - :ref:`GamepadControls ` - - by player scripts - - | Allows to alter behavior of the built-in script - | that handles player gamepad controls. - * - :ref:`ItemUsage ` - - by global scripts - - | Allows to extend or override built-in item usage - | mechanics. - * - :ref:`SkillProgression ` - - by local scripts - - | Control, extend, and override skill progression of the - | player. - * - :ref:`Settings ` - - by player, menu, and global scripts - - Save, display and track changes of setting values. - * - :ref:`MWUI ` - - by player and menu scripts - - Morrowind-style UI templates. - * - :ref:`UI ` - - by player scripts - - | High-level UI modes interface. Allows to override parts - | of the interface. - * - :ref:`Crimes ` - - by global scripts + * - :doc:`Camera ` + - |bdg-ctx-player| + - Allows to alter behavior of the built-in camera script without overriding the script completely. + * - :doc:`Controls ` + - |bdg-ctx-player| + - Allows to alter behavior of the built-in script that handles player controls. + * - :doc:`Crimes ` + - |bdg-ctx-global| - Commit crimes. + * - :doc:`GamepadControls ` + - |bdg-ctx-player| + - Allows to alter behavior of the built-in script that handles player gamepad controls. + * - :doc:`ItemUsage ` + - |bdg-ctx-global| + - Allows to extend or override built-in item usage mechanics. + * - :doc:`MWUI ` + - |bdg-ctx-menu| |bdg-ctx-player| + - Morrowind-style UI templates. + * - :doc:`Settings ` + - |bdg-ctx-global| |bdg-ctx-menu| |bdg-ctx-player| + - Save, display and track changes of setting values. + * - :doc:`SkillProgression ` + - |bdg-ctx-local| + - Control, extend, and override skill progression of the player. + * - :doc:`UI ` + - |bdg-ctx-player| + - High-level UI modes interface. Allows to override parts of the interface. diff --git a/docs/source/reference/lua-scripting/tables/packages.rst b/docs/source/reference/lua-scripting/tables/packages.rst index e66926e5e4..2485f2c0cd 100644 --- a/docs/source/reference/lua-scripting/tables/packages.rst +++ b/docs/source/reference/lua-scripting/tables/packages.rst @@ -1,49 +1,64 @@ -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -| Package | Can be used | Description | -+============================================================+====================+===============================================================+ -|:ref:`openmw.ambient ` | by player and menu | | Controls background sounds for given player. | -| | scripts | | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.animation ` | by local and | | Animation controls | -| | player scripts | | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.async ` | everywhere | | Timers and callbacks. | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.camera ` | by player scripts | | Controls camera. | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.core ` | everywhere | | Functions that are common for both global and local scripts | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.debug ` | by player scripts | | Collection of debug utils. | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.input ` | by player and menu | | User input. | -| | scripts | | -+------------------------------------------------------------+--------------------+---------------------------------------------------------------+ -|:ref:`openmw.interfaces