diff --git a/docs/.gitignore b/docs/.gitignore index f887e819..5e419902 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,2 +1,2 @@ _build -_html +*html* diff --git a/docs/conf.py b/docs/conf.py index 526bf796..8aee7a7b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -39,6 +39,8 @@ templates_path = ['_templates'] # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +# report broken references +nitpicky = True # -- Options for HTML output ------------------------------------------------- diff --git a/docs/ericw-tools.py b/docs/ericw-tools.py index a3c80ad8..20d9f0ac 100644 --- a/docs/ericw-tools.py +++ b/docs/ericw-tools.py @@ -54,6 +54,36 @@ def setup(app: Sphinx): indextemplate='pair: %s; light entity key', parse_node=parse_epair, ) + app.add_object_type( + directivename='spotlight-key', + rolename='spotlight-key', + indextemplate='pair: %s; spotlight entity key', + parse_node=parse_epair, + ) + app.add_object_type( + directivename='surflight-key', + rolename='surflight-key', + indextemplate='pair: %s; surface light entity key', + parse_node=parse_epair, + ) + app.add_object_type( + directivename='projlight-key', + rolename='projlight-key', + indextemplate='pair: %s; projected texture light entity key', + parse_node=parse_epair, + ) + app.add_object_type( + directivename='skylight-key', + rolename='skylight-key', + indextemplate='pair: %s; skylight entity key', + parse_node=parse_epair, + ) + app.add_object_type( + directivename='sunlight-key', + rolename='sunlight-key', + indextemplate='pair: %s; sunlight entity key', + parse_node=parse_epair, + ) app.add_object_type( directivename='classname', rolename='classname', diff --git a/docs/light.rst b/docs/light.rst index cf2d4121..cd0dc678 100644 --- a/docs/light.rst +++ b/docs/light.rst @@ -790,7 +790,7 @@ If used on func_detail* or func_group, a full qbsp pass need to be run. Integer. Default 0. Can be set to a nonzero value to make these brushes emit as surface lights - only from a light template with a matching :light-key:`_surflight_group` value. + only from a light template with a matching :surflight-key:`_surflight_group` value. .. bmodel-key:: "_lightcolorscale" "n" @@ -805,6 +805,9 @@ Light entity keys can be used in any entity with a classname starting with the first five letters "light". E.g. "light", "light_globe", "light_flame_small_yellow", etc. +Point Lights +------------ + .. light-key:: "light" "n" Set the light intensity. Negative values are also allowed and will @@ -821,7 +824,7 @@ with the first five letters "light". E.g. "light", "light_globe", Select an attenuation formaula for the light: - :: + .. code:: none 0 => Linear attenuation (default) 1 => 1/x attenuation @@ -850,30 +853,6 @@ with the first five letters "light". E.g. "light", "light_globe", light. RGB component values are between 0 and 255 (between 0 and 1 is also accepted). Default is white light ("255 255 255"). -.. light-key:: "target" "name" - - Turns the light into a spotlight, with the direction of light being - towards another entity with it's "targetname" key set to "name". - -.. light-key:: "mangle" "yaw pitch roll" - - Turns the light into a spotlight and specifies the direction of light - using yaw, pitch and roll in degrees. Yaw specifies the angle around - the Z-axis from 0 to 359 degrees and pitch specifies the angle from - 90 (straight up) to -90 (straight down). Roll has no effect, so use - any value (e.g. 0). Often easier than the "target" method. - -.. light-key:: "angle" "n" - - Specifies the angle in degrees for a spotlight cone. Default 40. - -.. light-key:: "_softangle" "n" - - Specifies the angle in degrees for an inner spotlight cone (must be - less than the "angle" cone. Creates a softer transition between the - full brightness of the inner cone to the edge of the outer cone. - Default 0 (disabled). - .. light-key:: "targetname" "name" Turns the light into a switchable light, toggled by another entity @@ -921,7 +900,49 @@ with the first five letters "light". E.g. "light", "light_globe", Number of lights to use for "_deviance". Default 16 (only used if "_deviance" is set). -.. light-key:: "_surface" "texturename" +.. light-key:: "_bouncescale" "n" + + Scales the amount of light that is contributed by bounces. Default is + 1.0, 0.0 disables bounce lighting for this light. + +.. light-key:: "_nostaticlight" "n" + + Set to 1 to make the light compiler ignore this entity (prevents it + from casting any light). e.g. could be useful with rtlights. + +Spotlights +---------- + +Supports all keys from `Point Lights`_ in addition to the following: + +.. spotlight-key:: "target" "name" + + Turns the light into a spotlight, with the direction of light being + towards another entity with it's "targetname" key set to "name". + +.. spotlight-key:: "mangle" "yaw pitch roll" + + Turns the light into a spotlight and specifies the direction of light + using yaw, pitch and roll in degrees. Yaw specifies the angle around + the Z-axis from 0 to 359 degrees and pitch specifies the angle from + 90 (straight up) to -90 (straight down). Roll has no effect, so use + any value (e.g. 0). Often easier than the "target" method. + +.. spotlight-key:: "angle" "n" + + Specifies the angle in degrees for a spotlight cone. Default 40. + +.. spotlight-key:: "_softangle" "n" + + Specifies the angle in degrees for an inner spotlight cone (must be + less than the "angle" cone. Creates a softer transition between the + full brightness of the inner cone to the edge of the outer cone. + Default 0 (disabled). + +Surface Lights +-------------- + +.. surflight-key:: "_surface" "texturename" Makes surfaces with the given texture name emit light, by using this light as a template which is copied across those surfaces. Lights are @@ -929,118 +950,160 @@ with the first five letters "light". E.g. "light", "light_globe", apart and positioned 2 units above the surfaces. To restrict this surface light config to a subset of brushes with - the "texturename" texture applied, see the :light-key:`_surflight_group` key. + the "texturename" texture applied, see the :surflight-key:`_surflight_group` key. -.. light-key:: "_surface_offset" "n" +.. surflight-key:: "_surface_offset" "n" - Controls the offset lights are placed above surfaces for :light-key:`_surface`. + Controls the offset lights are placed above surfaces for :surflight-key:`_surface`. Default 2. -.. light-key:: "_surface_spotlight" "n" +.. surflight-key:: "_surface_spotlight" "n" - For a surface light template (i.e. a light with :light-key:`_surface` set), + For a surface light template (i.e. a light with :surflight-key:`_surface` set), setting this to "1" makes each instance into a spotlight, with the direction of light pointing along the surface normal. In other words, it automatically sets "mangle" on each of the generated lights. -.. light-key:: "_surface_radiosity" "n" +.. surflight-key:: "_surface_radiosity" "n" - Whether to use Q1-style surface subdivision (0) or Q2-style + Whether to use Q1-style surface subdivision (0) or Q2-style surface radiosity (1) on this light specifically. - Use in conjunction with :light-key:`_surface`. + Use in conjunction with :surflight-key:`_surface`. - The default can be changed for all surface lights in a map with + The default can be changed for all surface lights in a map with worldspawn key :worldspawn-key:`_surflight_radiosity`. -.. light-key:: "_surflight_group" "n" +.. surflight-key:: "_surflight_group" "n" Integer, default 0. - For use with :light-key:`_surface` lights. + For use with :surflight-key:`_surface` lights. Can be set to a nonzero value to restrict this surface light template to only emit from brushes with a matching :bmodel-key:`_surflight_group` value. -.. light-key:: "_project_texture" "texture" + +Projected Texture Lights +------------------------ + +.. projlight-key:: "_project_texture" "texture" Specifies that a light should project this texture. The texture must be used in the map somewhere. -.. light-key:: "_project_mangle" "yaw pitch roll" + .. todo:: This is a qbsp limitation which could be fixed + +.. projlight-key:: "_project_mangle" "yaw pitch roll" Specifies the yaw/pitch/roll angles for a texture projection (overriding mangle). -.. light-key:: "_project_fov" "n" +.. projlight-key:: "_project_fov" "n" Specifies the fov angle for a texture projection. Default 90. -.. light-key:: "_bouncescale" "n" - Scales the amount of light that is contributed by bounces. Default is - 1.0, 0.0 disables bounce lighting for this light. +Sun Light +--------- -.. light-key:: "_sun" "n" +Also called directional light. Emitted from sky faces. + +.. sunlight-key:: "_sun" "n" Set to 1 to make this entity a sun, as an alternative to using the - sunlight worldspawn keys. If the light targets an info_null entity, + sunlight worldspawn keys. + +.. sunlight-key:: "target" "t" + + If the light targets an info_null entity, the direction towards that entity sets sun direction. The light itself is disabled, so it can be placed anywhere in the map. - The following light properties correspond to these sunlight settings: +.. sunlight-key:: "mangle" "yaw pitch roll" - :: + Alternate way of specifying sunlight direction. - light => _sunlight - mangle => _sunlight_mangle - deviance => _sunlight_penumbra - _color => _sunlight_color - _dirt => _sunlight_dirt - _anglescale => _anglescale - style => flicker style for styled sunlight - targetname => targetname for switchable sunlight - _suntexture => this sunlight is only emitted from faces with this texture name + Equivalent to worldspawn key :worldspawn-key:`_sunlight_mangle`. -.. light-key:: "_sunlight2" "n" +.. sunlight-key:: "light" "n" + + Equivalent to worldspawn key :worldspawn-key:`_sunlight`. + +.. sunlight-key:: "color" "r g b" + + Equivalent to worldspawn key :worldspawn-key:`_sunlight_color`. + +.. sunlight-key:: "deviance" "n" + + Equivalent to worldspawn key :worldspawn-key:`_sunlight_penumbra`. + +.. sunlight-key:: "_dirt" "n" + + Equivalent to worldspawn key :worldspawn-key:`_sunlight_dirt`. + +.. sunlight-key:: "_anglescale" "n" + + Equivalent to worldspawn key :worldspawn-key:`_anglescale`. + +.. sunlight-key:: "style" "n" + + Flicker style for styled sunlight. + +.. sunlight-key:: "targetname" "name" + + Targetname for switchable sunlight. + +.. sunlight-key:: "_suntexture" "texname" + + This sunlight is only emitted from faces with this texture name. Default is to be emitted from all sky textures. + + +Sky Light +--------- + +Hemisphere shaped light emitted from sky faces. + +.. skylight-key:: "_sunlight2" "n" Set to 1 to make this entity control the upper dome lighting emitted from sky faces, as an alternative to the worldspawn key :worldspawn-key:`_sunlight2`. The light entity itself is disabled, so it can be placed anywhere in the map. - The following light properties correspond to these sunlight settings: +.. skylight-key:: "_sunlight3" "n" - light - _sunlight2 + Same as :skylight-key:`_sunlight2`, but makes this sky light come from the lower hemisphere. - _color - _sunlight2_color +.. skylight-key:: "light" "n" - _dirt - _sunlight2_dirt + Sets the dome light brightness. Equivalent to worldspawn key :worldspawn-key:`_sunlight2`. - _anglescale - _anglescale +.. skylight-key:: "_color" "r g b" - style - flicker style for styled dome light + Sets the dome light color. Equivalent to worldspawn key :worldspawn-key:`_sunlight2_color`. - targetname - targetname for switchable sunlight +.. skylight-key:: "_dirt" "n" - _suntexture - this sunlight is only emitted from faces with this texture name + Equivalent to worldspawn key :worldspawn-key:`_sunlight2_dirt`. -.. light-key:: "_sunlight3" "n" +.. skylight-key:: "_anglescale" "n" - Same as :light-key:`_sunlight2`, but for the lower hemisphere. + Equivalent to worldspawn key :worldspawn-key:`_anglescale`. -.. light-key:: "_nostaticlight" "n" +.. skylight-key:: "style" "n" + + Flicker style for styled sky light. + +.. skylight-key:: "targetname" "name" + + Targetname for switchable skylight. + +.. skylight-key:: "_suntexture" "texname" + + This sky light is only emitted from faces with this texture name. Default is to be emitted from all sky textures. - Set to 1 to make the light compiler ignore this entity (prevents it - from casting any light). e.g. could be useful with rtlights. Lighting Channels ================= diff --git a/docs/requirements.in b/docs/requirements.in index 0e5d56b1..e49c34d9 100644 --- a/docs/requirements.in +++ b/docs/requirements.in @@ -1,2 +1,3 @@ -sphinx==6.2.1 -furo==2023.3.27 +sphinx==7.2.6 +furo==2024.1.29 +sphinx-autobuild==2024.2.4 diff --git a/docs/requirements.txt b/docs/requirements.txt index c0a3510c..95116729 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -4,58 +4,71 @@ # # pip-compile requirements.in # -alabaster==0.7.13 +alabaster==0.7.16 # via sphinx -babel==2.12.1 +babel==2.14.0 # via sphinx -beautifulsoup4==4.12.2 +beautifulsoup4==4.12.3 # via furo -certifi==2023.7.22 +certifi==2024.2.2 # via requests -charset-normalizer==3.1.0 +charset-normalizer==3.3.2 # via requests -docutils==0.19 +colorama==0.4.6 + # via + # sphinx + # sphinx-autobuild +docutils==0.20.1 # via sphinx -furo==2023.3.27 +furo==2024.1.29 # via -r requirements.in -idna==3.4 +idna==3.6 # via requests imagesize==1.4.1 # via sphinx jinja2==3.1.3 # via sphinx -markupsafe==2.1.2 +livereload==2.6.3 + # via sphinx-autobuild +markupsafe==2.1.5 # via jinja2 -packaging==23.1 +packaging==23.2 # via sphinx -pygments==2.15.1 +pygments==2.17.2 # via # furo # sphinx requests==2.31.0 # via sphinx +six==1.16.0 + # via livereload snowballstemmer==2.2.0 # via sphinx -soupsieve==2.4.1 +soupsieve==2.5 # via beautifulsoup4 -sphinx==6.2.1 +sphinx==7.2.6 # via # -r requirements.in # furo + # sphinx-autobuild # sphinx-basic-ng -sphinx-basic-ng==1.0.0b1 +sphinx-autobuild==2024.2.4 + # via -r requirements.in +sphinx-basic-ng==1.0.0b2 # via furo -sphinxcontrib-applehelp==1.0.4 +sphinxcontrib-applehelp==1.0.8 # via sphinx -sphinxcontrib-devhelp==1.0.2 +sphinxcontrib-devhelp==1.0.6 # via sphinx -sphinxcontrib-htmlhelp==2.0.1 +sphinxcontrib-htmlhelp==2.0.5 # via sphinx sphinxcontrib-jsmath==1.0.1 # via sphinx -sphinxcontrib-qthelp==1.0.3 +sphinxcontrib-qthelp==1.0.7 # via sphinx -sphinxcontrib-serializinghtml==1.1.5 +sphinxcontrib-serializinghtml==1.1.10 # via sphinx -urllib3==2.0.7 +tornado==6.4 + # via livereload +urllib3==2.2.0 # via requests