The DarkMod Wiki - User contributions [en]

Fan Mission Series

2022-04-13T06:29:51Z

Demagogue: /* William Steele series */

This article serves as an overview of the known existing FM series.

Over the years, ''The Dark Mod'' has accumulated a number of Fan Missions that form a larger interconnected series or an overarching/continuing narrative. Many series are connected by their main characters, some by other FM inter-related elements.

The FMs of each series are sorted in chronological order.

The number of each FM includes a link to its page on the official website.

The name of each FM includes a link to its page on the official TDM wiki.

Beware of potential (minor) spoilers behind the character links.

== Official campaigns ==

While all TDM missions are technically Fan Missions, the ones belonging to these official campaigns are as close as TDM will ever get to its own official in-game missions, or in-game story campaigns. These core missions for the base game are in slow and patient continuous development (due to TDM being a hobbyist project of a fan community), and have been gradually added to the base game over the course of several years.

For additional series by TDM authors, please see the next section.

=== Introduction campaign ===

The missions of this campaign serve as a gradual introduction into the setting and gameplay of ''The Dark Mod''. The missions are shorter and fairly easy, and gradually put the player's newly acquired skills to the test.

Currently, this is the only series that is bundled directly as part of the base game. By installing TDM, the first three missions available to you will be part of this official mini-campaign.

'''Series' characters:''' [[Thief Characters#Corbin|Corbin]] (protagonist), Paschal Murnerus, Moorish adventurers (background)

'''Series' status:''' In development, but currently on hiatus. 3 missions currently available, including the (generally plotless) training mission.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|0
!align=left|[[Training Mission (OM)|Training mission]]
|TDM dev team
|{{Forumlink|http://forums.thedarkmod.com/topic/9932-fan-mission-training-mission-20091017/}}
|2009-10-17 (original version)
|Training Jumping/Platforming
|Unique. The official tutorial mission of TDM, with open-ended gameplay.
|-
|-
|1
!align=left|[[A New Job (OM)|A New Job]]
|Springheel
|{{Forumlink|http://forums.thedarkmod.com/topic/18647-tdm-205-official-introductory-missions/}}
|2017-03-14
|City Missions Inn/Tavern
|
|-
|-
|2
!align=left|[[The Tears of Saint Lucia (OM)|The Tears of Saint Lucia]]
|TDM dev team
|{{Forumlink|http://forums.thedarkmod.com/topic/10579-fan-mission-the-tears-of-st-lucia-20081021/}} (original version), {{Forumlink|http://forums.thedarkmod.com/topic/18647-tdm-205-official-introductory-missions/}} (current version)
|2008-10-21 (original version), 2017-02-14 (current version, 3.0)
|Church/Cathedral
|[https://www.youtube.com/watch?v=yrGxoi3LSGg Briefing] ''{{TDM-FM|15|standalone release link}}''
|-
|}

== Individual authors' series ==

The majority of missions created for ''The Dark Mod''. For the sake of easier searching, these FM series are arranged in alphabetical order, based on their titles. In terms of release, a Single-mission (S) series consists of several single-mission FM releases over time (the commonest sort), while a Campaign (C) series is an FM containing a storyline consisting of several missions.

=== ''The Accountant'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Corbin|Corbin]] (protagonist)
* '''Series' status:''' Currently on hold.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|ac1|1}}
!align=left|[[The Accountant 1: Thieves and Heirs (FM)|The Accountant 1: Thieves and Heirs]]
|[[:Category:Missions by Goldwell|Goldwell]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19164-fan-mission-the-accountant-1-thieves-and-heirs-by-goldwell-20171108/}}
|2017-11-08
|Mansion/Estate
|[https://www.youtube.com/watch?v=Tk9DtOT4kjc Briefing]
|-

|-
|{{TDM-FM|ac2|2}}
!align=left|[[The Accountant 2: New in Town (FM)|The Accountant 2: New in Town]]
|[[:Category:Missions by Goldwell|Goldwell]]
|{{Forumlink|http://forums.thedarkmod.com/topic/18054-fan-mission-the-accountant-2-new-in-town-by-goldwell-20160509/}}
|2016-05-08
|Mansion/Estate
|[https://www.youtube.com/watch?v=xeuIO_GcYjQ Briefing] [https://www.youtube.com/watch?v=w6e_SJ0_JOM Gameplay trailer]
|-
|}

=== ''Away'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:'''
* '''Series' status:''' Currently on hold. Planned to continue.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-
|{{TDM-FM|away0|0}}
!align=left|[[Away 0: Stolen Heart (FM)|Away 0: Stolen Heart]]
|[[:Category:Missions by Geep|Geep]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20964-away-0-stolen-heart-by-geep-_atti_-20211112/}}
|2021-11-12
|Inn/Tavern, Jail/Prison, Museum Heist, Bank Job
|
|-
|{{TDM-FM|airpocket|1}}
!align=left|[[Away 1: Air Pocket (FM)|Away 1: Air Pocket]]
|[[:Category:Missions by Geep|Geep]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20252-fan-mission-away-1-air-pocket-by-geep-20200207/}}
|2020-02-06
|Pirate/Ship
|
|-
|}

=== ''Chronicles of Skulduggery'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Elyas_Thorne|Elyas Thorne]] (protagonist)
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|cos0_thief|0}}
!align=left|[[Chronicles of Skulduggery 0: To Catch a Thief (FM)|To Catch a Thief]]
|[[:Category:Missions by Bienie|Bienie]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/21156-fan-mission-chronicles-of-skulduggery-0-to-catch-a-thief-20211120/}}
|2021-11-20
|City Missions Mansion/Estate
|
|-
|-
|{{TDM-FM|127|1}}
!align=left|[[Chronicles of Skulduggery 1: Pearls and Swine (FM)|Pearls and Swine]]
|[[:Category:Missions by Bienie|Bienie]]
|{{Forumlink|https://forums.thedarkmod.com/topic/19439-chronicles-of-skulduggery-pearls-and-swine/}}
|2018-05-25
|City Missions
|
|-
|-
|{{TDM-FM|137|2}}
!align=left|[[Chronicles of Skulduggery 2: A Precarious Position (FM)|A Precarious Position]]
|[[:Category:Missions by Bienie|Bienie]]
|{{Forumlink|https://forums.thedarkmod.com/topic/19975-fan-mission-chronicles-of-skulduggery-2-a-precarious-position-20190504/}}
|2019-05-03
|City Missions
|
|-
|-
|{{TDM-FM|149|3}}
!align=left|[[Chronicles of Skulduggery 3: Sacricide (FM)|Sacricide]]
|[[:Category:Missions by Bienie|Bienie]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20483-fan-mission-chronicles-of-skulduggery-3-sacricide-20200718/}}
|2020-07-18
|City Missions
|
|-
|}

=== ''Corbin'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Corbin|Corbin]] (protagonist), cardinal Laurenti (background), Keshka brotherhood members (antagonists)
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|builders_influence|1}}
!align=left|[[The Builder's Influence (FM)|The Builder's Influence]]
|[[:Category:Missions by RailGun|RailGun]], [[:Category:Missions by Springheel|Springheel]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10811-fan-mission-the-builders-influence-20100320/}}
|2010-03-20 (original version), 2010-03-23 (version 2.0)
|Castle/Fortress
|
|-
|-
|{{TDM-FM|score_to_settle|2}}
!align=left|[[A Score to Settle (FM)|A Score to Settle]]
|[[:Category:Missions by Springheel|Springheel]]
|{{Forumlink|http://forums.thedarkmod.com/topic/12894-fan-mission-48-a-score-to-settle-by-springheel-20110701/}}
|2011-07-01
|City Missions
|
|-
|-
|{{TDM-FM|follow|3}}
!align=left|[[A Reputation to Uphold (FM)|A Reputation to Uphold]]
|[[:Category:Missions by Springheel|Springheel]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16204-fan-mission-a-reputation-to-uphold-by-springheel/}}
|2014-04-18
|City Missions
|
|-
|-
|{{TDM-FM|matterofhours|4}}
!align=left|[[A Matter of Hours (FM)|A Matter of Hours]]
|[[:Category:Missions by Springheel|Springheel]]
|{{Forumlink|http://forums.thedarkmod.com/topic/18809-fan-mission-a-matter-of-hours-by-springheel-2842017/}}
|2017-04-28
|Warehouse
|
|-
|}

=== ''Crucible of Omens'' series ===

* '''Description:''' Though originally planned as a major campaign for future releases of TDM, development progress has been halted.
* '''Release:''' Released as Single-mission (S), possibly would have been a Campaign (C) if finished.
* '''Series' status:''' Development halted, campaign apparently cancelled. Only 1 mission has been completed and made available.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|bcd|1}}
!align=left|[[Crucible of Omens: Behind closed doors (FM)|Crucible of Omens: Behind closed doors]]
|[[:Category:Missions by Bikerdude|Bikerdude]], Crucible of Omens Team
|{{Forumlink|http://forums.thedarkmod.com/topic/17627-crucible-of-omens-behind-closed-doors-by-bikerdude-the-crucible-team-updated-18122015/}}
|2015-12-19
|City Missions
|-
|}

=== ''The Hare in the Snare'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:'''
* '''Series' status:''' Planned to continue.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|hareinthesnare|1}}
!align=left|[[The Hare in the Snare: Part 1 (FM)|The Hare in the Snare: Part 1]]
|[[:Category:Missions by Frost_Salamander|Frost_Salamander]] & [[:Category:Missions by Kerry000|Kerry000]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20883-fan-mission-the-hare-in-the-snare-part-1}}
|2021-04-09
|City Missions Inn/Tavern
|
|-
|}

=== ''Hidden Hands'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|hhi|1}}
!align=left|[[Hidden Hands 1: Initiation (FM)|Initiation]]
|[[:Category:Missions by JackFarmer|JackFarmer]]
|{{Forumlink|http://forums.thedarkmod.com/index.php?/topic/19796-hidden-hands-initiation-27122018/}}
|2018-12-27
|Mansion/Estate Ship
|
|-
|-
|{{TDM-FM|hhvf|2}}
!align=left|[[Hidden Hands 2: Vitalic Fever (FM)|Vitalic Fever]]
|[[:Category:Missions by JackFarmer|JackFarmer]]
|{{Forumlink|http://forums.thedarkmod.com/index.php?/topic/20051-hidden-hands-vitalic-fever-20072019/}}
|2019-07-20
|Mansion/Estate
|
|-
|-
|{{TDM-FM|hhtlc|3}}
!align=left|[[Hidden Hands 3: The Lost Citadel (FM)|The Lost Citadel]]
|[[:Category:Missions by JackFarmer|JackFarmer]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20490-hidden-hands-the-lost-citadel-23072020}}
|2020-07-23
|Castle/Fortress
|
|-
|-
|-
|{{TDM-FM|hhta|4}}
!align=left|[[Hidden Hands 4: The Anomaly (FM)|The Anomaly]]
|[[:Category:Missions by JackFarmer|JackFarmer]]
|{{Forumlink|https://forums.thedarkmod.com/index.php?/topic/20909-hidden-hands-the-anomaly}}
|2021-05-01
|Castle/Fortress Forest
|
|-
|-
|}

=== ''In A Time of Need'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Terry|Terry]] (supporting)
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|timeofneed|1}}
!align=left|[[In A Time of Need 1 (FM)|In A Time Of Need]]
|[[:Category:Missions by Kyyrma|Kyyrma]]
|{{Forumlink|http://forums.thedarkmod.com/topic/15354-fan-mission-in-a-time-of-need-by-kyyrma-20131112/}}
|2013-11-12
|Mansion/Estate
|
|-

|-
|{{TDM-FM|breakingout|2}}
!align=left|[[In A Time of Need 2: Breaking Out the Fence (FM)|Breaking Out the Fence]]
|[[:Category:Missions by Kyyrma|Kyyrma]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16091-fan-mission-breaking-out-the-fence-17032014-by-kyyrma/}}
|2014-03-17
|City Missions
|
|-
|}

=== ''Master thief Corso'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief Characters#Corso|Corso]] (protagonist), [[Thief Characters#Mingus|Mingus]] (background, supporting)
* '''Series' status:''' On hiatus.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|lockner|1}}
!align=left|[[Lockner Manor (FM)|Lockner Manor]]
|[[:Category:Missions by Buck28|buck28]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16452-new-mission-lockner-manor/}}
|2014-08-02
|Mansion/Estate Inn/Tavern
|
|-

|-
|{{TDM-FM|briarwood|2}}
!align=left|[[Briarwood Cathedral (FM)|Briarwood Cathedral]]
|[[:Category:Missions by Buck28|buck28]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16644-briarwood-cathedral/}}
|2014-10-29
|Church/Cathedral Horror
|Winner of the [[Fan Mission Contests#2014 Halloween Speed-build Contest|2014 Halloween Speed-build Contest]].
|-
|}

=== ''No Honor Among Thieves'' campaign ===

* '''Release:''' Campaign (C)
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|nhat3|1}}
!align=left|[[No Honor Among Thieves (FM)|Politics]]
|[[:Category:Missions by Goldchocobo|Goldchocobo]], [[:Category:Missions by RailGun|RailGun]], [[:Category:Missions by Mortem Desino|Mortem Desino]], [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10993-fan-mission-no-honor-among-thieves-20100429/}}
|2010-04-29 (original version), 2015-05-30 (current version, 3.0)
|Church/Cathedral
|
|-

|-
|{{TDM-FM|nhat3|2}}
!align=left|[[No Honor Among Thieves (FM)|A Night Out on the Town]]
|[[:Category:Missions by Goldchocobo|Goldchocobo]], [[:Category:Missions by RailGun|RailGun]], [[:Category:Missions by Mortem Desino|Mortem Desino]], [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10993-fan-mission-no-honor-among-thieves-20100429/}}
|2010-04-29 (original version), 2015-05-30 (current version, 3.0)
|City Missions
|
|-

|-
|{{TDM-FM|nhat3|3}}
!align=left|[[No Honor Among Thieves (FM)|No Honor Among Anyone (a.k.a. Forest)]]
|[[:Category:Missions by Goldchocobo|Goldchocobo]], [[:Category:Missions by RailGun|RailGun]], [[:Category:Missions by Mortem Desino|Mortem Desino]], [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10993-fan-mission-no-honor-among-thieves-20100429/}}
|2010-04-29 (original version), 2015-05-30 (current version, 3.0)
|Outdoor/Pagan, Mansion/Estate
|
|-
|}

=== ''Of Brambles and Thorns'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|onesteptoofar|1}}
!align=left|[[One Step Too Far (FM)|One Step Too Far]]
|[[:Category:Missions by Dragofer|Dragofer]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16457-fan-mission-one-step-too-far-by-dragofer-20140804/}}
|2014-08-04
|Pirate Horror
|
|-

|-
|{{TDM-FM|river|2}}
!align=left|[[Down by the Riverside (FM)|Down by the Riverside]]
|[[:Category:Missions by Dragofer|Dragofer]]
|{{Forumlink|http://forums.thedarkmod.com/topic/18402-fan-mission-down-by-the-riverside-by-dragofer-20160925/}}
|2016-09-25
|Mansion/Estate Ship
|
|-
|}

=== ''Penny Dreadful'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' Gerald Foxley (protagonist)
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|penny1_1|1}}
!align=left|[[Penny Dreadful 1: The Grail of Regrets (FM)|Penny Dreadful 1: The Grail of Regrets]]
|[[:Category:Missions by Melan|Melan]]
|{{Forumlink|http://forums.thedarkmod.com/topic/14952-fan-mission-penny-dreadful-by-melan-20130728/}}
|2013-07-27
|Horror
|
|-
|-
|{{TDM-FM|penny2_1|2}}
!align=left|[[Penny Dreadful 2: All the Way Up (FM)|Penny Dreadful 2: All the Way Up]]
|[[:Category:Missions by Melan|Melan]], [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16387-fan-mission-penny-dreadful-2-by-melan-and-bikerdude-2014078/}}
|2014-07-08
|Thieves' Highway (Rooftop)
|[https://www.youtube.com/watch?v=WmPfCfbeWvg Trailer]
|-
|-
|{{TDM-FM|penny3|3}}
!align=left|[[Penny Dreadful 3: Erasing the Trail (FM)|Penny Dreadful 3: Erasing the Trail]]
|[[:Category:Missions by Melan|Melan]], [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/18200-fan-mission-penny-dreadful-3-by-melan-and-bikerdude-20160710/}}
|2016-07-09
|City Missions
|
|-
|}

=== ''Quinn Co.'' campaign ===

* '''Release:''' Campaign (C) (originally single mission (S))
* '''Series' characters:''' TBA
* '''Series' status:''' Completed and released.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|quinn|1}}
!align=left|[[Quinn Co. (FM)|La Banque Bienveillante]]
|[[:Category:Missions by Airship Ballet|Airship Ballet]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16702-fan-mission-la-banque-bienveillante-by-airship-ballet-20141122/}}
|2014-11-22 (original version), 2015-02-04 (current version, bundled with Chase Mercantile)
|Bank Jobs
|
|-
|-
|{{TDM-FM|quinn|2}}
!align=left|[[Quinn Co. (FM)|Chase Mercantile]]
|[[:Category:Missions by Airship Ballet|Airship Ballet]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16912-fan-mission-chase-mercantile-by-airship-ballet-20150204/}}
|2015-02-04 (now bundled with La Banque Bienveillante)
|Bank Jobs
|
|-
|}

=== ''Selis Woderose'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Selis_Woderose|Selis Woderose]] (protagonist)
* '''Series' status:''' Currently on hiatus.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|flakebridge|1}}
!align=left|[[Selis Woderose 1: Flakebridge Monastery (FM)|Flakebridge Monastery]]
|[[:Category:Missions by Jesps|Jesps]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11991-fm-flakebridge-monastery-by-jesps/}}
|2010-12-05
|Church/Cathedral
|
|-
|-
|{{TDM-FM|rake_off|2}}
!align=left|[[Selis Woderose 2: Rake-off (FM)|Rake-off]]
|[[:Category:Missions by Jesps|Jesps]]
|{{Forumlink|http://forums.thedarkmod.com/topic/12846-fm-rake-off-19-06-2011/}}
|2011-06-19
|Castle/Fortress
|
|-
|}

=== ''Shadowcursed'' series ===

* '''Release:''' Single-mission (S) for the first mission and Campaign (C) for the second mission.
* '''Series' characters:''' [[Thief_Characters#Bolen|Bolen]] (protagonist)
* '''Series' status:''' Ongoing, currently on hiatus.
* '''Ancilliary materials:''' ''[http://www.amazon.com/Shadowcursed-ebook/dp/B00BYEW02M Shadowcursed]'' novella (e-book)

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|requiem|1}}
!align=left|[[Requiem (FM)|Requiem]]
|[[:Category:Missions by Moonbo|Moonbo]]
|{{Forumlink|http://forums.thedarkmod.com/topic/15101-fan-mission-requiem-by-gelo-moonbo-fleisher-2013106/}}
|2013-10-08
|Church/Cathedral Lost Civilizations
|[https://web.archive.org/web/20160409012413/https://community.eidosmontreal.com/blogs/thief-mod-winners Winner] of the 2014 official ''[http://forums.thedarkmod.com/topic/15956-square-enix-and-amazoncom-announce-thief-mod-contest/ Thief Mod Competition]'' by Square Enix & Amazon.com.
|-
|-
|{{TDM-FM|ahouseoflockedsecrets|2}}
!align=left|[[A House of Locked Secrets (FM)|A House of Locked Secrets]]
|[[:Category:Missions by Moonbo|Moonbo]]
|{{Forumlink|http://forums.thedarkmod.com/topic/17163-fan-mission-a-house-of-locked-secrets-by-gelo-moonbo-fleisher-20150528/}}
|2015-05-29
|Church/Cathedral Mansion/Estate
|[https://www.youtube.com/watch?v=f5NuTJEZ8VE Trailer]
|-
|}

=== ''Shadows of Northdale'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief Characters#Corbin|Corbin]] (protagonist)
* '''Series' status:''' Ongoing, currently in gradual development.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|northdale1|1}}
!align=left|[[Shadows of Northdale Act I (FM)|Shadows of Northdale ACT I: A Curious Mind]]
|[[:Category:Missions by Goldwell|Goldwell]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19368-fan-mission-shadows-of-northdale-act-i-by-goldwell-20180323/}}
|2018-03-23
|City Missions
|[https://www.youtube.com/watch?v=p4nP3lYd6wg Briefing]
|-

|-
|{{TDM-FM|northdale2|2}}
!align=left|[[Shadows of Northdale Act II (FM)|Shadows of Northdale ACT II: Down the Rabbit Hole]]
|[[:Category:Missions by Goldwell|Goldwell]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19936-fan-mission-shadows-of-northdale-act-ii-by-goldwell-20190320/}}
|2019-03-20
|City Missions
|[https://www.youtube.com/watch?v=KO-eIOX9nqI Briefing]
|-
|}

=== ''St Alban'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|caduceus|1}}
!align=left|[[St Alban 1: The Caduceus of St Alban (FM)|The Caduceus of St. Alban]]
|[[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11644-the-caduceus-of-st-alban-vertical-fm-contest-entry-aug-8th-2010/}}
|2010-08-23 (original version), 2010-08-26 (version 1.5.5)
|Church/Cathedral
|
|-
|-
|{{TDM-FM|cathedral|2}}
!align=left|[[St Alban 2: St Albans Cathedral (FM)|St. Albans Cathedral]]
|[[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16343-fan-mission-st-albans-cathedral-v20-11062014/}} (current, 2.0 version)
|2010-11-01 (original version), 2014-06-11 (version 2.0)
|Church/Cathedral
|
|-
|}

=== ''Talbot'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' Talbot
* '''Series' status:''' Ongoing, currently on hiatus.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|returntothecity|1}}
!align=left|[[Talbot 2: Return to the City (FM)|Return to the City]]
|[[:Category:Missions by Melan|Melan]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10509-fan-mission-return-to-the-city-by-melan-20100110/}} (original version), {{Forumlink|http://forums.thedarkmod.com/topic/12390-fan-mission-return-to-the-city-v2-01032011/}} (version 2.0)
|2010-01-10 (original version), 2015-01-03 (2.0), 2015-01-03 (current version, 3.0)
|City Missions
|Winner of the [[Fan Mission Contests#2009 Grand Christmas Contest|2009 Grand Christmas Contest]].
|-
|-
|{{TDM-FM|fauchard1_1|2}}
!align=left|[[Talbot 3: Fiasco at Fauchard Street (FM)|Fiasco at Fauchard Street]]
|[[:Category:Missions by Melan|Melan]]
|{{Forumlink|http://forums.thedarkmod.com/topic/12655-fan-mission-fiasco-at-fauchard-street-by-melan-20110501/}}
|2011-05-01
|Thieves' Highway (Rooftop)
|
|-
|}

'''''Note:''' [[Sir Talbot's Collateral (FM)|Sir Talbot's Collateral]] by Bikerdude and Baal is actually an unrelated mission, just with a similarly named character.''

=== ''Thief's Den'' series ===

* '''Release:''' Single-mission (S)
* '''Description:''' The ''de facto'' oldest FM series in ''The Dark Mod''. Follow the skillful thief Farrell as he navigates the criminal underworld of [[The City|Bridgeport]] and the surrounding world.
* '''Series' characters:''' [[Thief Characters#Farrell|Farrell]] (protagonist), [[Thief Characters#Sebastian_Creep|Sebastian Creep]] (supporting)
* '''Series' status:''' Currently on hiatus.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-
|-
|{{TDM-FM|thiefsden|1}}
!align=left|[[Thief's Den 1: Thief's Den (FM)|Thief's Den]]
|[[:Category:Missions by Fidcal|Fidcal]], [[:Category:Missions by Greebo|Greebo]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11347-fan-mission-thiefs-den-re-release-by-fidcal20100704/}}
|2008-01-18 (original version), 2010-07-04 (version 2.0)
|City Missions
|
|-
|-
|{{TDM-FM|chalice1_1|2}}
!align=left|[[Thief's Den 2: The Chalice of Kings (FM)|The Chalice of Kings]]
|[[:Category:Missions by Fidcal|Fidcal]] (original version), [[:Category:Missions by Bikerdude|Bikerdude]], [[:Category:Missions by Xarg|Xarg]] (edits, version 2.0)
|{{Forumlink|http://forums.thedarkmod.com/topic/9935-fan-mission-chalice-of-kings-by-fidcal-20091017/}}
|2009-10-15 (original version), 2015-09-24 (version 2.0)
|Castle/Fortress
|
|-
|-
|{{TDM-FM|heartv2|3}}
!align=left|[[Thief's Den 3: The Heart of Lone Salvation (FM)|The Heart of Lone Salvation]]
|[[:Category:Missions by Fidcal|Fidcal]], Baddcog, [[:Category:Missions by Bikerdude|Bikerdude]]
|{{Forumlink|http://forums.thedarkmod.com/topic/10878-fan-mission-the-heart-of-lone-salvation-by-fidcal-baddcog-bikerdude-20100402/}}
|2010-04-02 (original version), 2014-04-12 (version 2.0)
|City Missions
|
|-
|-
|{{TDM-FM|alchemist|4}}
!align=left|[[Thief's Den 4: The Alchemist (FM)|The Alchemist]]
|[[:Category:Missions by Sotha|Sotha]], [[:Category:Missions by Fidcal|Fidcal]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11170-fan-mission-the-alchemist-by-sotha-fidcal20100601/}}
|2010-06-01 (original version) 2010-06-04 (update)
|City Missions
|
|-
|}

=== ''Thomas Porter'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#Thomas Porter|Thomas Porter]] (protagonist), [[Thief_Characters#Lark Butternose|Lark Butternose]] (supporting), [[Noble/Wealthy_Characters#Godfrey_Knighton|Godfrey Knighton]] (background)
* '''Series' status:''' Concluded.
* '''Overview:''' [http://forums.thedarkmod.com/topic/15179-the-thomas-porter-series/ Courtesy of] Sotha.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|mandrasola|1}}
!align=left|[[Thomas Porter 1: Mandrasola (FM)|Mandrasola]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/12575-fan-mission-mandrasola-by-sotha-20110410/}}
|2011-04-10
|City Missions
|
|-
|-
|{{TDM-FM|knighton_manor|2}}
!align=left|[[Thomas Porter 2: Knighton Manor (FM)|Knighton Manor]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11898-fan-mission-the-knighton-manor-by-sotha-20101109/}}
|2010-11-09
|Mansion/Estate
|
|-
|-
|{{TDM-FM|beleaguered_fence|3}}
!align=left|[[Thomas Porter 3: The Beleaguered Fence (FM)|The Beleaguered Fence]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11298-fan-mission-the-beleaguered-fence-by-sotha-20100623/}}
|2010-06-23
|Jail/Prison
|
|-
|-
|{{TDM-FM|glenham_tower|4}}
!align=left|[[Thomas Porter 4: Glenham Tower (FM)|Glenham Tower]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/11423-fan-mission-the-glenham-tower-by-sotha-20100717/}}
|2010-07-17
|Castle/Fortress Horror
|Winner of the [[Fan_Mission_Contests#2010_Summer_Vertical_Contest|2010 Summer Vertical Contest]].
|-
|-
|{{TDM-FM|transaction|5}}
!align=left|[[Thomas Porter 5: The Transaction (FM)|The Transaction]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/12408-fan-mission-the-transaction-by-sotha-20110304/}}
|2011-03-04
|City Missions
|
|-
|-
|{{TDM-FM|phrase_book|6}}
!align=left|[[Thomas Porter 6: The Phrase Book (FM)|The Phrase Book]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/13799-fan-mission-the-phrase-book-by-sotha-20120512/}}
|2012-05-11
|City Missions Thieves' Highway (Rooftop)
|
|-
|-
|{{TDM-FM|lich_queens_demise|7}}
!align=left|[[Thomas Porter 7: The Lich Queen's Demise (FM)|The Lich Queen's Demise]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/14826-fan-mission-the-lich-queens-demise-by-sotha-20130520/}}
|2013-05-20
|Horror
|
|-
|}

=== ''Ulysses'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' Ulysses (protagonist)
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|ulysses_genesis|1}}
!align=left|[[Ulysses 1: Genesis (FM)|Ulysses: Genesis]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16428-fan-mission-ulysses-genesis-by-sotha-20140724/}}
|2014-07-24
|Mansion/Estate
|
|-

|-
|{{TDM-FM|u2_flock|2}}
!align=left|[[Ulysses 2: Protecting the Flock (FM)|Ulysses: Protecting the Flock]]
|[[:Category:Missions by Sotha|Sotha]]
|{{Forumlink|http://forums.thedarkmod.com/topic/17162-fan-mission-ulysses-2-protecting-the-flock-by-sotha-20150528/}}
|2015-05-28
|Church/Cathedral
|
|-
|}

=== ''Vengeance for a Thief'' campaign ===

* '''Release:''' Single-mission (S) for the first two published missions, Campaign (C) for the final release that also includes a new first mission.
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|vfat3|1}}
!align=left|[[Vengeance for a Thief (FM)|The Angel's Tear]]
|[[:Category:Missions by Sir Taffsalot|Sir Taffsalot]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16953-the-complete-vengeance-for-a-thief-campaign/}}
|2015-02-16
|Church/Cathedral
|
|-

|-
|{{TDM-FM|vfat1|2}}
!align=left|[[Vengeance for a Thief (FM)|A Pawn in the Game]]
|[[:Category:Missions by Sir Taffsalot|Sir Taffsalot]]
|{{Forumlink|http://forums.thedarkmod.com/topic/14068-fan-mission-vengeance-for-a-thief-part-1-by-sir-taffsalot-06092012/}}
|2012-09-06
|Jail/Prison
|''{{TDM-FM|62|standalone release link}}''
|-

|-
|{{TDM-FM|vfat2|3}}
!align=left|[[Vengeance for a Thief (FM)|The Art of Revenge]]
|[[:Category:Missions by Sir Taffsalot|Sir Taffsalot]]
|{{Forumlink|http://forums.thedarkmod.com/topic/15051-fan-mission-vengeance-for-a-thief-part-2-by-sir-taffsalot-06092013/}}
|2013-09-06
|Museum Heists
|''{{TDM-FM|75|standalone release link}}''
|-

|}

=== ''Volta'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' TBA
* '''Series' status:''' TBA

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|volta1_3|1}}
!align=left|[[Volta I: The Stone (FM)|Volta and the Stone]]
|[[:Category:Missions by Kingsal|Kingsal]]
|{{Forumlink|http://forums.thedarkmod.com/topic/18087-fan-mission-volta-and-the-stone-by-kingsal-05262016/}}
|2016-05-27
|Mansion/Estate City Missions
|
|-

|-
|{{TDM-FM|cauldron_v2_2|2}}
!align=left|[[Volta II: Cauldron of the Gods (FM)|Volta 2: Cauldron of the Gods]]
|[[:Category:Missions by Kingsal|Kingsal]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19207-fan-mission-volta-ii-cauldron-of-the-gods-by-kingsal-113017-update-v20/}}
|2017-11-30
|Lost Civilizations
|[https://www.youtube.com/watch?v=SRRCRVFHruc Briefing]
|-
|}

=== ''William Steele'' series ===

* '''Release:''' Single-mission (S)
* '''Series' characters:''' [[Thief_Characters#William_Steele|William Steele]] (protagonist)
* '''Series' status:''' Ended with the passing of grayman, rest in peace.

{|class="wikitable sortable" border=1 style="border-collapse: collapse;" cellspacing=0 cellpadding=2 width=100%
|-
!bgcolor=#d0d0e0 width="1%"|No.
!bgcolor=#d0d0e0 width="21%"|Fan Mission Title
!bgcolor=#d0d0e0 width="11%"|Author(s)
!bgcolor=#d0d0e0 width="4%" class="unsortable"|Forum link
!bgcolor=#d0d0e0 width="5%"|Releases
!bgcolor=#d0d0e0 width="5%"|Mission Type
!bgcolor=#d0d0e0 width="5%"|Notes
|-

|-
|{{TDM-FM|ws1_north|1}}
!align=left|[[William Steele 1: In the North (FM)|In the North]]
|[[:Category:Missions by Grayman|grayman]]
|{{Forumlink|http://forums.thedarkmod.com/topic/14214-fan-mission-in-the-north-by-grayman-20121020/}}
|2012-10-20
|Mansion/Estate
|
|-

|-
|{{TDM-FM|ws2_homeagain|2}}
!align=left|[[William Steele 2: Home Again (FM)|Home Again]]
|[[:Category:Missions by Grayman|grayman]]
|{{Forumlink|http://forums.thedarkmod.com/topic/15919-fan-mission-home-again-by-grayman-2014212/}}
|2014-02-12
|Thieves' Highway (Rooftop)
|
|-

|-
|{{TDM-FM|ws3_cleighmoor|3}}
!align=left|[[William Steele 3: Cleighmoor (FM)|Cleighmoor]]
|[[:Category:Missions by Grayman|grayman]]
|{{Forumlink|http://forums.thedarkmod.com/topic/16011-fan-mission-cleighmoor-by-grayman-201431/}}
|2014-03-01
|Sewers Jail/Prison
|
|-

|-
|{{TDM-FM|ws4_warrens|4}}
!align=left|[[William Steele 4: The Warrens (FM)|The Warrens]]
|[[:Category:Missions by Grayman|grayman]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19618-fan-mission-the-warrens-by-grayman-201891/}}
|2018-09-01
|City Missions
|
|-

|-
|{{TDM-FM|ws5_commerce|5}}
!align=left|[[William Steele 5: Commerce Bank (FM)|Commerce Bank]]
|[[:Category:Missions by Grayman|grayman]]
|{{Forumlink|http://forums.thedarkmod.com/topic/19957-fan-mission-commerce-bank-by-grayman-2019410/}}
|2019-04-10
|Bank Jobs
|
|-

|}

== Note ==

For a key to the descriptions of each Mission Type, please see [[Fan_Missions_for_The_Dark_Mod#Table_notes|this overview]].

== See also ==

*[[Fan Missions for The Dark Mod]] - Main article on TDM fan missions.

[[Category:Fan Missions|S]]

A Full-Screen Slide in Mid-Game

2021-11-27T00:52:21Z

Demagogue: /* For More */

''by Geep, 2021''
==Overview==
Suppose you want to briefly show some text on-screen, but the existing TDM message gui’s don’t quite do what you want. Here’s how you can easily modify them.

Start by creating an atdm:gui_message entity in your map. Then, in the Entity Inspector, rename it to atdm_gui_message_slide, and alter these 2 lines to:
gui guis/my_slide.gui
show <number of seconds you want slide to appear>
Unlike the unaltered case, for what we're doing here, the values of this entity's spawnargs "lines" and "text" will be ignored. Also, the slide will disappear abruptly at "show" time, not fade out.

Arrange for your player to trigger this entity. Finally, we will create and customize my_slide.gui. In particular, we will make it possible for the user to terminate the slide early, by clicking the LMB on it. The text we will display will be hardcoded into the .gui, not passed as a spawnarg or (as would be the case with readables) retrieved from an .xd file.

The Doom GUI language is not a thing of beauty. Some places require semi-colons at line ends; some places forbid them. Sometimes you need quotes; sometimes not. Persevere.

==Case 1 – Transparent Background, White Letters==
In your FM’s “guis” folder, create my_slide.gui with content:
windowDef MySlide
{
visible 1
rect 0,0,640,480 // x, y, w, h. Origin upper-left screen corner.
onAction {
set "MySlide::visible" "0";
}
windowDef Text1 {
rect 10, 10, 620, 460 // x, y (relative to parent origin), w, h. Adjust to control margins.
text "Let's try word wrapping. This box is within screen bounds. Sometimes, with word wrapping, you can use a box that slightly exceeds screen width."
textscale 1
font "fonts/popsies"
}
}
Almost always, you use “rect 0,0,640,480” in the parent windowDef to establish a logical coordinate system stretched over the screen dimensions. By default, a TDM menu cursor will appear, to remind the user that they can exit early by clicking... really anywhere. You can suppress this cursor with "nocursor 1". Choose the font from the standard TDM ones (e.g., carleton is used for briefings). Adjust the font size with float "textscale", but 1 or less is best.

The text will be word-wrapped and left-justified. You can add "textalign 1" to center it (Sometimes with "textalign 1", the first line stays left-justified; ugh. If so, stick in some leading spaces).

This is not very different than the standard atdm:gui_message treatment with the "...no_art" gui. However, if you want to have titles and paragraphs with different fonts, sizes, locations, or margins, you can just add additional windowDefs. More about that below. Another usage would be to tweak the margins to provide a subtitle, instead of full-screen text.

==Case 2 – Opaque Black Background, White Letters==
Here, we have a slide in the style of old-time silent movie captions.
windowDef MySlide
{
visible 1
rect 0,0,640,480
backcolor 0, 0, 0, 1 // Black background
onAction {
set "MySlide::visible" "0";
set "gui::MySlideDone" "1";
}
windowDef Text1 { ... same as previous example ... }
}
With an opaque full-screen background, it's often necessary for the rest of the game to know when the slide is done, particularly if it’s up more than a few seconds. So onAction sets a variable, that can then be polled for in a script, shown next.
==Sample Script Code to Put Up a Slide then Wait==
void full_screen_slide()
{
sys.trigger($atdm_gui_message_slide); // show the slide
// Optionally add code here to move player to blue room.
// We’ll need to get the gui’s overlay handle, from the attached default scriptobject, which is “tdm_gui_message”.
// By casting, we get access to it here.
tdm_gui_message e = $atdm_gui_message_slide;
// Can take a while for the overlay handle to be created and for e.gui to be non-zero.
// If spawnarg "delay" is zero, the default, a 0.1 second delay is imposed.
float handlenum = 0;
while(handlenum == 0)
{
handlenum = e.gui;
sys.wait(0.1);
}
float maxtime = $atdm_gui_message_slide.getFloatKey("show");
float slide_done == 0;
while(maxtime > 0)
{
slide_done = $player1.getGuiFloat(handlenum, "MySlideDone");
if(slide_done == 1) // user did gui's onAction, with LMB
break;
maxtime -= 0.1;
sys.wait(0.1);
}
// Optionally add code here to move player from blue room.
$player1.setGuiFloat(handlenum, "MySlideDone", 0); // reset just in case
}

==Case 3 – Opaque Image Background, Black Letters==
windowDef MySlide
{
visible 1
rect 0,0,640,480
background "models/darkmod/props/textures/parchment_freshpaper"
onAction {
set "MySlide::visible" "0";
set "gui::MySlideDone" "1";
}
windowDef Text1 {
rect 10, 10, 620, 460 // x, y (relative to parent origin), w, h
text " ...same text as Case 1... "
forecolor 1, 1, 1, 1 // Black opaque font
textscale 1
font "fonts/popsies"
}
}
===Variants===
We’re using a stock TDM background here, but you can have your FM include a custom .jpg, .tga, or .dds image as background. As is usual with TDM, "background" assumes the filepath from the FM’s root, and does not want the file extension to be stated here.

As an alternative, you could just burn the text into the background image. But translators will be unhappy unless you also provide them with the corresponding text-free image.

==Case 4 – Two-Level Image Background, Black Letters==
There are a number of pre-existing TDM "parchment" and "scroll" backgrounds that have wide transparent perimeters. You could substitute one of these directly, in the style of Case 3, so you see the game world around the edges. Instead, we use "backcolor" to set an opaque black background (as in Case 2), and define the scroll atop it within a child windowDef:

windowDef MySlide
{
visible 1
rect 0,0,640,480
backcolor 0, 0, 0, 1 // Black background
onAction {
set "MySlide::visible" "0";
set "gui::MySlideDone" "1";
}
windowDef Scroll1{
visible 1
rect 0,0,640,480 // x, y, w, h. This can be bigger than the parent if you want to reduce transparent perimeter
background "guis/assets/readables/scroll"
}
windowDef Text1 { ... same as previous example ... }
}

==An Actual Example==
An outgrown of Case 4 can be found in FM "Away 0: Stolen Heart". There comes a point where the player can ask to skip an upcoming video cutscene, typically because they've already seen it. In that case, when the player gets to where the video cutscene would play, a plausible full-screen slide is shown instead. Information on the slide summarizes, in re-imagined form, what the cutscene would show.

[[File:Away0 if skip first cutscene.jpg|thumb|center|A more-complex example of an actual slide. Click to expand.]]

The "Continue" text provides a mental target for the cursor, but the gamer can really click anywhere. The custom .gui in this case uses multiple windowDefs with differnt margins, font colors, and font sizes to position text blocks atop the scroll.

windowDef CutSceneReplacementSlide
{
visible 1
rect 0,0,640,480 // x, y, w, h. Origin upper-left
backcolor 0, 0, 0, 1
onAction {
set "CutSceneReplacementSlide::visible" "0";
set "gui::FirstCutsceneReplacementSlideDone" "1";
}
windowDef Scroll1 {
visible 1
rect 0,0,640,480 // x, y, w, h. This can be bigger than the parent if you want to reduce transparent perimeter
background "guis/assets/readables/scroll"
}
windowDef Text1 {
rect 10, 30, 620, 460 // x, y, w, h. Margins enlarged to keep text on opaque upper portion of Scroll1
text "What Emily Will Say in Her Diary"
forecolor 1, 1, 1, 1 // White opaque font
textscale 0.5
textalign 1 // Centered
font "fonts/carleton"
}
windowDef Text2 {
rect 100, 70, 440, 250 // x, y, w, h. Margins enlarged to keep text on opaque middle portion of Scroll1
text "I startled from my prayers. There he was in my room, & he brought what we need! I snatched the key from him & flung open the long-locked door, the night air so sweet. My passion arose, and he responded ."
forecolor 0, 0, 0, 1 // Black opaque font
textscale 0.4
font "fonts/popsies"
}
windowDef Text3 {
rect 100, 280, 440, 250 // x, y, w, h. Margins enlarged to keep text on opaque middle portion of Scroll1
text "But horrors! I heard Bleda's gait, his footsteps approach. He would kill us! I bolted out the door, shouting ' Follow Me'!"
forecolor 0, 0, 0, 1 // Black opaque font
textscale 0.4
font "fonts/popsies"
}
windowDef Text4 {
rect 10, 420, 590, 40 // x, y, w, h. Margins enlarged to keep text on opaque lower portion of Scroll1
text "Continue"
forecolor 1, 1, 1, 1 // White opaque font
textscale 0.5
textalign 1 // Centered
font "fonts/carleton"
}
}

The corresponding script function (in emily_related.script) is far more complicated than what was discussed earlier, because it handles the video, sound, and additional FM-specific chores for story continuity.

==For More==
The information here draws on 2004-vintage GUI tutorials by Doom creator John Carmack, but adapted to TDM and the context here.

[[Mission Title Screen while Loading]] has more about the Doom3 GUI layout language with further examples.

You should use a text editor for GUI files. The vintage built-in GUI editor (console command "editGUIs") has become unusable.

[[Full-Screen Video Cutscenes]] has more about deploying "skippable" video cutscenes.

{{editing}}
[[Category:Video and cutscenes]]
[[Category:Scripting]]
[[Category:Fonts]]

Location Settings

2017-09-19T11:18:05Z

Demagogue: /* Ambient sound */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, or for reading a book, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix mentioned above, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. If you open the console, it will report that the override ambient is playing. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop. Using the function sys.waitFor( $[speaker_name]); after running the speaker is supposed to automatically wait the duration, but this needs to be tested.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $tdm_location_settings_1.setKey( "override", "[snd_name]"); to turn on an override sound and $[tls_1].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas. Also be sure to use the right name for the location settings entity. It may not have a "_1" suffix.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "tdm_location_settings_1"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. (Volume is not included however. You'd just use the speaker property "s_volume" directly, but you'd need to restore it after the override is over if you don't want the change applying to all sounds.) You can change them dynamically in the same way as override. If you have multiple overrides, some with fading and some without, and want to revert to the default fading without looking it up, you can enter "-1" as the value of a property and it uses the default value.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches or pierces the portal you want as a boundary, and it will mark that portal as a location boundary. (Note, you only make one separator per portal. In the photo example below, the one separator is piercing the portal.)

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with one info_locationseparator touching the portal (actually piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

:*There's a bug with setting ambient_light to 0 0 0 (to be fixed in 2.05), so use 0.004 0.004 0.004 if you want to remove ambient light from a location.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2017-09-19T11:17:05Z

Demagogue: /* info_locationseparator */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, or for reading a book, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix mentioned above, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. If you open the console, it will report that the override ambient is playing. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop. Using the function sys.waitFor( $[speaker_name]); after running the speaker is supposed to automatically wait the duration, but this needs to be tested.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $tdm_location_settings_1.setKey( "override", "[snd_name]"); to turn on an override sound and $[tls_1].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas. Also be sure to use the right name for the location settings entity. It may not have a "_1" suffix.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "tdm_location_settings_1"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. (Volume is not included however. You'd just use the speaker property "s_volume" directly, but you'd need to restore it after the override is over if you don't want the change applying to all sounds.) You can change them dynamically in the same way as override. If you have multiple overrides, some with fading and some without, and want to revert to the default fading without looking it up, you can enter "-1" as the value of a property and it uses the default value.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches or pierces the portal you want as a boundary, and it will mark that portal as a location boundary. (Note, you only make one separator per portal. In the photo example below, the one separator is piercing the portal.)

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

:*There's a bug with setting ambient_light to 0 0 0 (to be fixed in 2.05), so use 0.004 0.004 0.004 if you want to remove ambient light from a location.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

How to add Textures to The Dark Mod

2016-05-21T08:58:34Z

Demagogue: /* Move the Texture to the right Location */

== Create your texture ==
This is mostly artwork. Be sure to start off with useful raw material with a reasonably high resolution. Where possible, work from photo-references. A basic guide can be found here: [[Texture Creation - Basic Tutorial]].

A few things to remember: Make sure your texture dimensions are a power of 2 (eg, 128, 256, 512, 1024, etc). Other common mistakes can be found here: [[Common Texture Mistakes]]
{{Things-To-Remember|
* Use good source material
* All image dimensions must be powers of two: 64, 128, 256, 512, 1024 (don't go beyond 1024).
* Avoid lighting baked into the diffusemap
* Keep your PSD/Gimp working version safe!}}
== Save your Texture in the correct Format ==
Save the diffusemap, the normalmap and an optional specularmap to a TGA file. The '''[[Texture Guidelines]]''' will help you choosing the correct resolution. A TGA version of your diffusemap is supposed to be uploaded to our hi-res repository for future reference (see below).

Once your TGA file is saved, you will have to create DDS files for the diffuse and specular (not the normalmap) as well. These are smaller in size and can be loaded faster by the engine. Follow the '''[[DDS creation]]''' guide to learn how to create the DDS files in the correct formats.

Also, create an editor image out of your diffusemap. The editor image dimension should be 256x256 pixels and the file should be saved in the JPG format. Add the '''_ed''' postfix to the filename name (like <code>mytexture_ed.jpg</code>).
{{Things-To-Remember|
* Most textures don't need speculars
* Create DDS for your diffusemap and specularmap.
* Keep TGA version of your diffusemap and specularmap.
* Create a TGA version of your normalmap (uncompressed, no RLE).
* Create a JPG editor image (max. 256px)}}
== Name your Texture ==
The following convention should be used for naming all new texture additions to TDM (many existing textures do not follow this convention, and over time effort will be made to update them). The goal is consistency among material names based on ordered characteristics.

'''Some or all''' of the following may apply to any given material:

# '''Object Type''' descriptor first (mostly for very specific-use textures) - it's a window, a door, a chest...
# '''Material''' descriptor next - made from marble, wood, mud...
# '''Size''' descriptor next - it is large, small...
# '''Quality''' descriptors next - texture-wise, it is rough, new, cracked...
# '''Color''' descriptors next - what color is it? red, green...
# '''Number Increment''' next - which of the list is it? 001, 002...
# '''Tiling''' and '''Image Type''' descriptors, if needed (file only, not material definition - see below)

If establishing precedent (creating a new '''Size''' descriptor, e.g., "huge"), try to avoid ambiguity and unnecessary overlapping with other descriptors (e.g., "enormous"), and set a good example others will follow.

'''Examples:'''

1. ''slate_large_cracked_grey_001''

This name omits an '''Object Type''' descriptor, instead starting with the '''Material''' descriptor - it is a general, non-specialized texture.

Why is this preferred? Some existing materials are named by quality descriptor first (e.g., 'cracked_slate...'). This is an inconvenience for the user, because they were looking for a 'slate', not a 'cracked'.

2. ''door_wood_battered_005''

This name omits a '''Size''' descriptor and a '''Color''' descriptor.

Why is this preferred? In the case of a model name (which this convention also covers), or a specific object type texture like the above, some existing assets are named by quality descriptor first (e.g., 'battered_wood...'). This is an inconvenience for the user, because they were looking for a 'door', not a 'battered'.

Be sure to rename all your DDS file extensions to a '''lowercase''' '''.dds''' (the Compressonator always creates files with uppercase extension, TDM requires them to be lowercase).

If your texture tiles only in one direction, include the phrase '''tiling_1d''' at the end of the name. If your texture does not tile (repeat) at all, add the phrase '''nontiling'''. So, a normalmap could be names as '''concrete_dirt01_tiling1d_local.tga'''.

Diffusemaps should have no extension to their name. Normalmaps should have a '''_local''' extension at the end of their name. Specular maps should have a '''_s''' extension, the editor images go with an '''_ed''' extension.
{{Things-To-Remember|
* Choose descriptive names for your texture, while following TDM convention
* Add the suffix '''tiling_1d'''/'''nontiling''' to the filename where appropriate
* Diffusemap: '''mytexture.dds''' (note the '''lowercase''')
* Normalmap: '''mytexture_local.tga'''
* Editor image: '''mytexture_ed.jpg''' (max. 256 pixels in size)
* (Optional) Specularmap: '''mytexture_s.dds'''}}

== Move the Texture to the right Location ==
When you upload textures, be sure to upload the files to the right spot. The '''[[Texture Folder Structure]]''' can help you finding the right folder for your texture.

The .dds diffuse and specular go in the '''dds/textures/''' folder structure. The .tga normalmap goes in the '''textures/''' folder structure. Also, the texture may not render properly unless it's nested inside "../textures/darkmod/.." and for a custom texture (only for FM use) you should use "../textures/darkmod/your_texture_folder" in both the parent Darkmod folder (for mapping) and the same folder structure inside your pk4 (for release). Note that there is a peculiarity of the Doom 3 engine not being able to load DDS textures that are more than five folders deep. The deepest level allowed would be something along the lines of dds/textures/darkmod/door/metal/. This is something to be watched out for.
{{Things-To-Remember|
* Move the DDS textures into the '''dds/textures/...''' tree.
* Move the TGA and JPG files into the '''textures/...''' tree.
* Don't save DDS files into folders more than 5 levels deep.}}

== Create your Shader Definition (Material) ==
Your material entry should be added to the .mtr file that has the same name as the folder your texture is saved in. For example, the material entry for a texture saved in '''textures/darkmod/wood/panels''' should be saved in the .mtr file, '''tdm_wood_panels.mtr'''. See also the [[Material File Naming Convention]].

You should name your material entry the same name as your diffuse texture, including the folder path structure (eg, "textures/darkmod/wood/panels/rectangle_oak_face"). (Do not add .tga or .dds to the end, and also skip the dds/ folder prefix.)

The only exception is when multiple shaders are using the same diffusemap, or when your texture doesn't tile (or tiles in only one direction). In the latter case, you would add '''/nontiling/''' or "/tiling_1d/''' to the end of the shader folder (a 'virtual' folder, essentially). ''(The textures used to be separated like that in the actual folder structure, but due to D3's inability to read .dds files five folders deep, they had to be moved.)''
{{Things-To-Remember|
* Create your shader in the correct file (tdm_xxx_yyy.mtr) following the [[Material File Naming Convention]]
* The shader name for tiling textures is the same as the diffusemap
* Nontiling/tiling_1d textures go into a "virtual" subfolder nontiling/ or tiling_1d/
* You don't need to specify file extensions (.dds/.tga/.jpg) to the material defs, this is automatically guessed by the engine.
* You don't need the '''dds/''' folder prefix to reference the DDS textures.
* Be sure to include the frob highlight code (see [[Basic Material File#Add_the_Frob_Highlight_Stage|Basic Material File]])
* You '''must''' include Dark Mod's ambient light stage (see [[Virtual Ambient Light Textures]])}}

== Upload the Textures ==
Once, you have checked your texture in-game (and are pleased with the results), you'll need to upload the files to our SVN repository. This requires that you have a valid username/password for SVN, which you can request from sparhawk.

The .tga of the diffuse and specular is needed as well in case we ever want to make modifications to the texture or new textures based on the old. Opening and resaving .dds files results in loss of detail, so all new versions of textures should be made from the .tga files. So, additional to the textures needed for the engine and editor (diffuse/normal/specular/editorimage) you're encouraged to upload the uncompressed textures to the hires repository.

The hires repository is located at '''<nowiki>https://<InsertDarkmodServerHere>/svn/darkmod_hires/trunk/tga_backup/</nowiki>'''. As only diffuse/speculars are compressed in DDS format, these are the only two that need to be uploaded in TGA format. The TGA files should be named just like the DDS versions and should be located in the analogous folder than they are in the main repository, but below the tga_backup/ folder. For instance tga_backup/textures/darkmod/stone/etc.

The hires TGA can be RLE-compressed to save some space, but this is not too important. Uncompressed TGAs are only important for the textures used by the engine itself.

As last part, it would be nice to have the actual working versions (Photoshop/Gimp source files) stored on the server too. This is of course a large upload, but having the source files is very valuable. For this purpose, there is another repository '''texture_src''' installed at '''<nowiki>https://<InsertDarkmodServerHere>/svn/texture_src/</nowiki>'''.
{{Things-To-Remember|
* Upload the diffuse, normal, (specular,) and editor image to the regular darkmod SVN.
* Upload the (RLE-compressed) TGA diffusemap and specularmap to the darkmod_hires SVN repository (into the '''tga_backup''' subfolder).
* Upload the working source file (PSD/Gimp) to the '''texture_src''' repository.}}
{{tutorial-textures}}
__NOTOC__

How to add Textures to The Dark Mod

2016-05-21T08:57:20Z

Demagogue: /* Move the Texture to the right Location */

== Create your texture ==
This is mostly artwork. Be sure to start off with useful raw material with a reasonably high resolution. Where possible, work from photo-references. A basic guide can be found here: [[Texture Creation - Basic Tutorial]].

A few things to remember: Make sure your texture dimensions are a power of 2 (eg, 128, 256, 512, 1024, etc). Other common mistakes can be found here: [[Common Texture Mistakes]]
{{Things-To-Remember|
* Use good source material
* All image dimensions must be powers of two: 64, 128, 256, 512, 1024 (don't go beyond 1024).
* Avoid lighting baked into the diffusemap
* Keep your PSD/Gimp working version safe!}}
== Save your Texture in the correct Format ==
Save the diffusemap, the normalmap and an optional specularmap to a TGA file. The '''[[Texture Guidelines]]''' will help you choosing the correct resolution. A TGA version of your diffusemap is supposed to be uploaded to our hi-res repository for future reference (see below).

Once your TGA file is saved, you will have to create DDS files for the diffuse and specular (not the normalmap) as well. These are smaller in size and can be loaded faster by the engine. Follow the '''[[DDS creation]]''' guide to learn how to create the DDS files in the correct formats.

Also, create an editor image out of your diffusemap. The editor image dimension should be 256x256 pixels and the file should be saved in the JPG format. Add the '''_ed''' postfix to the filename name (like <code>mytexture_ed.jpg</code>).
{{Things-To-Remember|
* Most textures don't need speculars
* Create DDS for your diffusemap and specularmap.
* Keep TGA version of your diffusemap and specularmap.
* Create a TGA version of your normalmap (uncompressed, no RLE).
* Create a JPG editor image (max. 256px)}}
== Name your Texture ==
The following convention should be used for naming all new texture additions to TDM (many existing textures do not follow this convention, and over time effort will be made to update them). The goal is consistency among material names based on ordered characteristics.

'''Some or all''' of the following may apply to any given material:

# '''Object Type''' descriptor first (mostly for very specific-use textures) - it's a window, a door, a chest...
# '''Material''' descriptor next - made from marble, wood, mud...
# '''Size''' descriptor next - it is large, small...
# '''Quality''' descriptors next - texture-wise, it is rough, new, cracked...
# '''Color''' descriptors next - what color is it? red, green...
# '''Number Increment''' next - which of the list is it? 001, 002...
# '''Tiling''' and '''Image Type''' descriptors, if needed (file only, not material definition - see below)

If establishing precedent (creating a new '''Size''' descriptor, e.g., "huge"), try to avoid ambiguity and unnecessary overlapping with other descriptors (e.g., "enormous"), and set a good example others will follow.

'''Examples:'''

1. ''slate_large_cracked_grey_001''

This name omits an '''Object Type''' descriptor, instead starting with the '''Material''' descriptor - it is a general, non-specialized texture.

Why is this preferred? Some existing materials are named by quality descriptor first (e.g., 'cracked_slate...'). This is an inconvenience for the user, because they were looking for a 'slate', not a 'cracked'.

2. ''door_wood_battered_005''

This name omits a '''Size''' descriptor and a '''Color''' descriptor.

Why is this preferred? In the case of a model name (which this convention also covers), or a specific object type texture like the above, some existing assets are named by quality descriptor first (e.g., 'battered_wood...'). This is an inconvenience for the user, because they were looking for a 'door', not a 'battered'.

Be sure to rename all your DDS file extensions to a '''lowercase''' '''.dds''' (the Compressonator always creates files with uppercase extension, TDM requires them to be lowercase).

If your texture tiles only in one direction, include the phrase '''tiling_1d''' at the end of the name. If your texture does not tile (repeat) at all, add the phrase '''nontiling'''. So, a normalmap could be names as '''concrete_dirt01_tiling1d_local.tga'''.

Diffusemaps should have no extension to their name. Normalmaps should have a '''_local''' extension at the end of their name. Specular maps should have a '''_s''' extension, the editor images go with an '''_ed''' extension.
{{Things-To-Remember|
* Choose descriptive names for your texture, while following TDM convention
* Add the suffix '''tiling_1d'''/'''nontiling''' to the filename where appropriate
* Diffusemap: '''mytexture.dds''' (note the '''lowercase''')
* Normalmap: '''mytexture_local.tga'''
* Editor image: '''mytexture_ed.jpg''' (max. 256 pixels in size)
* (Optional) Specularmap: '''mytexture_s.dds'''}}

== Move the Texture to the right Location ==
When you upload textures, be sure to upload the files to the right spot. The '''[[Texture Folder Structure]]''' can help you finding the right folder for your texture.

The .dds diffuse and specular go in the '''dds/textures/''' folder structure. The .tga normalmap goes in the '''textures/''' folder structure. Also, the texture may not render properly unless it's nested inside "../textures/darkmod/.." and for a custom texture (only for FM use) you should have "../textures/darkmod/your_texture_folder" in both the parent Darkmod folder (for mapping) and the same folder structure inside your pk4 (for release). Note that there is a peculiarity of the Doom 3 engine not being able to load DDS textures that are more than five folders deep. The deepest level allowed would be something along the lines of dds/textures/darkmod/door/metal/. This is something to be watched out for.
{{Things-To-Remember|
* Move the DDS textures into the '''dds/textures/...''' tree.
* Move the TGA and JPG files into the '''textures/...''' tree.
* Don't save DDS files into folders more than 5 levels deep.}}

== Create your Shader Definition (Material) ==
Your material entry should be added to the .mtr file that has the same name as the folder your texture is saved in. For example, the material entry for a texture saved in '''textures/darkmod/wood/panels''' should be saved in the .mtr file, '''tdm_wood_panels.mtr'''. See also the [[Material File Naming Convention]].

You should name your material entry the same name as your diffuse texture, including the folder path structure (eg, "textures/darkmod/wood/panels/rectangle_oak_face"). (Do not add .tga or .dds to the end, and also skip the dds/ folder prefix.)

The only exception is when multiple shaders are using the same diffusemap, or when your texture doesn't tile (or tiles in only one direction). In the latter case, you would add '''/nontiling/''' or "/tiling_1d/''' to the end of the shader folder (a 'virtual' folder, essentially). ''(The textures used to be separated like that in the actual folder structure, but due to D3's inability to read .dds files five folders deep, they had to be moved.)''
{{Things-To-Remember|
* Create your shader in the correct file (tdm_xxx_yyy.mtr) following the [[Material File Naming Convention]]
* The shader name for tiling textures is the same as the diffusemap
* Nontiling/tiling_1d textures go into a "virtual" subfolder nontiling/ or tiling_1d/
* You don't need to specify file extensions (.dds/.tga/.jpg) to the material defs, this is automatically guessed by the engine.
* You don't need the '''dds/''' folder prefix to reference the DDS textures.
* Be sure to include the frob highlight code (see [[Basic Material File#Add_the_Frob_Highlight_Stage|Basic Material File]])
* You '''must''' include Dark Mod's ambient light stage (see [[Virtual Ambient Light Textures]])}}

== Upload the Textures ==
Once, you have checked your texture in-game (and are pleased with the results), you'll need to upload the files to our SVN repository. This requires that you have a valid username/password for SVN, which you can request from sparhawk.

The .tga of the diffuse and specular is needed as well in case we ever want to make modifications to the texture or new textures based on the old. Opening and resaving .dds files results in loss of detail, so all new versions of textures should be made from the .tga files. So, additional to the textures needed for the engine and editor (diffuse/normal/specular/editorimage) you're encouraged to upload the uncompressed textures to the hires repository.

The hires repository is located at '''<nowiki>https://<InsertDarkmodServerHere>/svn/darkmod_hires/trunk/tga_backup/</nowiki>'''. As only diffuse/speculars are compressed in DDS format, these are the only two that need to be uploaded in TGA format. The TGA files should be named just like the DDS versions and should be located in the analogous folder than they are in the main repository, but below the tga_backup/ folder. For instance tga_backup/textures/darkmod/stone/etc.

The hires TGA can be RLE-compressed to save some space, but this is not too important. Uncompressed TGAs are only important for the textures used by the engine itself.

As last part, it would be nice to have the actual working versions (Photoshop/Gimp source files) stored on the server too. This is of course a large upload, but having the source files is very valuable. For this purpose, there is another repository '''texture_src''' installed at '''<nowiki>https://<InsertDarkmodServerHere>/svn/texture_src/</nowiki>'''.
{{Things-To-Remember|
* Upload the diffuse, normal, (specular,) and editor image to the regular darkmod SVN.
* Upload the (RLE-compressed) TGA diffusemap and specularmap to the darkmod_hires SVN repository (into the '''tga_backup''' subfolder).
* Upload the working source file (PSD/Gimp) to the '''texture_src''' repository.}}
{{tutorial-textures}}
__NOTOC__

Texture Creation - Basic Tutorial

2016-05-21T08:50:55Z

Demagogue: /* Create your material file */

{{tutorial-textures}} {{Original_Reference|SneaksieDave|3814}}
A game like this needs a TON of textures. So I wanted to try to learn how to do this mysterious, wonderous, magick...

Erm, well, it's not magick. Far from it, in fact. This tutorial isn't for those of you who already know how to do this*, and already know it's not magick. This tutorial is for the rest of us, those who have been too scared or lazy to even bother asking "how do I?", like me. (It's the former, honest!)

== Prerequisites ==

You can use Gimp or Photoshop on Windows, for Linux you should use Gimp. So you'll need either of the two programs Gimp/Photoshop and the corresponding set of plugins:

=== Photoshop ===

* [http://developer.nvidia.com/object/photoshop_dds_plugins.html Nvidia normal map plugin]

=== Gimp ===

* [http://code.google.com/p/gimp-normalmap/#Download GIMP normalmap plugin]
* [http://gimp-texturize.sourceforge.net/download.html GIMP texturize plugin]
* [http://code.google.com/p/gimp-dds/ Gimp DDS plugin]

If you are using Kubuntu/Ubuntu, you can also install the <code>gimp-texturize</code> and <code>gimp-resynthesizer</code> packages.

To compile Gimp plugins from source, install the following packages and their dependecies:

* libgimp2.0-dev
* libgtk1.2-dev
* libglut3-dev (for the DDS plugin)

== Get your source picture ==

This could be anything from a photograph you took, to a free texture download from the internet (see [[Texture Sources]]), to a hand drawn picture, if you're one of those fortunate enough to possess that skill - though we generally prefer to work from photo-reference when possible.

If you do want to take photos, some tips:
* try to shoot on an overcast day; the diffuse light will remove most unwanted shadows
* try to take the photo as perfectly face-on to the surface as you can manage.
If your end result isn't perfect, don't worry, there are ways to fix it (transform->skew, to name one)
* Make sure that all parts of your photo you want to use as texture are in focus (e.g. sharp). Unsharp parts cannot be fixed later, at least not without a big quality loss!
* try to select an area that will be tile-able (if that's what you want)
* try to capture a large area such that you'll have enough to work with, but not so big that your resolution on the final product will suffer

== Create the diffuse map ==

The diffuse map is a tilable (usally) image which gives the color infomation, but does not contain lighting or height information for the texture. It is stored as dds with dxt1 or dxt3 compression for use in Doom 3 and as 24 bit TGA (with or without RLE) for the hires repository.

If your image has lighting baked in (shadows/highlights), you should remove it: [[Remove Shadows in Source Images]].

This is just a basic tutorial for creating textures. For further information about creating Diffusemaps, read [[Advanced Tips for Creating Diffusemaps]].

=== Photoshop ===

Inspect the source image. If you're going to tile it, try to find a regular repeating area. This is only to make your job easier. You can tile anything, really, but it depends on how much work you want to give yourself. If you don't know what I mean here, at the next step you will.

After you've chosen a rough tile-able area (from here forward I'm going to assume you are doing a tiled texture), crop that area out, and size your image to the desired size ratio. I wouldn't go lower than 1024 resolution at this stage of the work, or you'll start losing picture quality quickly. So set it to 2048X1024, or 1024X1024, etc. The reason we need to fix the size ratio (not the final size) at this stage is for the next step.

==== Set the offset ====

Go to Filter->Other->Offset. You want to set the horizontal and vertical to be exactly half of your cropped picture's width and height. That will make the opposite edges of the texture meet each other in the middle of the view, so you can make it really tile-able.

==== Make the seams disappear ====
See those seams running right down the middle of the pic, vertically and horizontally? You have to make them disappear. Get to know the clone tool. (Google...) There are many other ways to shuffle pixels too, but I'll leave the specifics up to you. This is usually the hardest, most time consuming step.

Once you've blended the lines away, run the Offset filter again to restore the correct layout of your pic, and save it out in a nice high quality (but not too big to manage) format. This is the "diffuse" image. We're using 24bit TGA for TDM.

=== Gimp ===

Use the <code>texturizer</code> or the <code>resynthezier</code> plugin - these are very easy to work with and make manual work almost needless.

== Create a normal map ==

The Normalmap tells the renderer in which direction a corresponding place on the diffusemap is facing, so that it can be shaded according to the present lightsources in the scene. It is stored as uncompressed 24 bit TGA (no RLE!) for use in Doom 3. You will learn the basics about creating Normalmaps here. For further information: [[Normalmaps, How to Make Good Ones]].

=== Photoshop ===

Now that the diffuse is done, using that same pic, open Filter->Nvidia Tools->NormalMapFilter. You'll probably have to play with the values for a while to get a feel for it, and to get a normal map you are happy with. This is a rough approximation method, by no means as accurate as actually modelling a texture (see [[Wall Texture Tutorial]] or [[Creating Textures with Normals out of Models]]), but it works pretty good in most cases. Basically, it will make light areas "high" and dark areas "low". Learn how to manipulate color levels in Photoshop, and you'll be making good normal maps with the Nvidia filter in no time. Generally, use values of 3 or 4 for simple things like woodgrain or nails. Values of 12 or higher can be used for more 3d effects.

If you think about it, there are countless ways to adjust the image (in fact, you're not even restricted to using the diffuse image as the base of the normal map...) to get desired results - inverting colors, brightness and contrast controls, painting over areas, gradients, etc. It's a "feel" thing, so you'll have to develop that for yourself. After creating your desired normal map (try not to make it too blurry, or too sharp, or too bumpy - yuck), save it out as you did with the diffuse image, with "_local" appended.

=== Gimp ===

This is a rough guide by a non-expert as I (fidcal) do it so at least there is something here. It assumes you have made a temporary greyscale image file saved as say nameGrey.tga with the brighter areas representing the high ground and darker means low as described elsewhere ready to make your make normal map. It assumes you've just downloaded Gimp and its Normalmap plugin (ESSENTIAL!), maybe configured it a bit so don't know much about it but just want a dumb list to follow.

* Open Gimp
* Gimp consists of separate floating windows with no main window so select the toolbar window > file menu > and open your greyscale image file.
* You can enlarge/maximize the window and zoom with the mouse wheel if you want.
* Menu > filters > map > normalmap
* On the normal map dialog, Click 3D map preview; it will make more sense then.
* On the normal map dialog, in the 'scale' box there is zero by default which is useless as a default as this seems to be the scale of depth. Enter 50 for a start.
* On the 3D preview dialog there is a window with a panel in it. Grab the panel with your left mouse button and drag it around. Now you should see a rough 3D impression of your image.
* If you have no idea what you're doing (like me) leave the scale at 50 as a reasonable value, otherwise adjust it according to your knowledge. Maybe come back here later if you feel your final result is not deep enough or too deep. Similarly leave the other controls or adjust if you know what you are doing.
* On the normal map dialog click OK.
* On Gimp's image window you should now see your greyscale image has been converted probably blue looking with depressions, eg inverted the heights; that's OK.
* Save as name_local.tga in the correct dark mod texture folder where your main texture is.
* A mini dialog pops up : RLE compression - set this UNchecked, and 'origin at bottom left' - leave this checked. Click OK.
* I had a lot of programs open including Doom so it seemed to hang a long time but eventually saved.
* You close Gimp by closing that toolbar window so I guess that's its nearest thing to a main window.

That's it.

== Create an editor image ==
As the diffusemap is very large it takes some time loading it into the editor, this is why DarkRadiant/DoomEd support the display of lowres editor images replacements. Just resize the diffusemap down to max. 256 pixels and save it in JPG format, but be sure to attach the '''_ed''' suffix.

== Add a specular map ==
The specularmap tells the renderer how shiny a corresponding place on the diffusemap is. It is stored as dds and its dimensions are typically scaled down to be half as big as those of the diffusemap.

If you want a specular map, the process is even more subjective. There are countless ways in Photoshop to adjust color and light level and even invert everything or parts or mask out areas. Specular maps work as such: Darker is rendered as dull, lighter is rendered as shiny. Get it? Think of the possibilities, and have fun with it. You can get some pretty amazing results with just minutes of work. Save that image out as you did the diffuse, '''with "_s" appended'''.

Note that most surface types don't need a specular map. Only shiny surfaces, like metal or wet stone, really need one, while wood, cobbles, canvas, leaves, dirt etc. should not have a specular map.

== Create your material file ==

Create a material for the texture (see [[Basic Material File]]). In the materials folder, locate the material file where you texture fits in best. Then add the following:

<pre>
textures/darkmod/your_desired_editor_texture_folder/your_texture_name
{
// Use one of the predefined surface types like stone, glass, wood
stone
// or use this:
// surfaceType 15
// and make the first word in the description below your texture type,
// like so:
// description "foliage" (This is a grass texture)

description "Add here a little description of your texture"
qer_editorimage textures/darkmod/your_file_folder/your_texture_name_ed

bumpmap textures/darkmod/your_file_folder/your_texture_name_local
diffusemap textures/darkmod/your_file_folder/your_texture_name
specularmap textures/darkmod/your_file_folder/your_texture_name_s

// This is the code required for frob highlighting this texture
{
if ( parm11 > 0 )
blend gl_dst_color, gl_one
map _white.tga
rgb 0.40 * parm11
}
{
if ( parm11 > 0 )
blend add
map textures/darkmod/your_file_folder/your_texture_name
rgb 0.15 * parm11
}

// The following two blocks are required for the ambient shading:
// TDM Ambient Method Related
{
if (global5 == 1)
blend add
map textures/darkmod/your_file_folder/your_texture_name
scale 1, 1
red global2
green global3
blue global4
}

}
</pre>

Oh, and on Windows, use Wordpad, not Notepad. That's it. Your new texture should appear in both the editor and in-game.

== Summary ==
So you see, it's really quite simple:
* Crop the desired area
* Make it tileable if necessary
* Generate a normal map
* Generate an editor image
* Create a specular map if you want one
* Include it in a material file
* DONE

The most important thing though, is to obey the [[Texture Guidelines]].

== Further Information ==

* [[Common Texture Mistakes]]
* [[How to add Textures to The Dark Mod]]
* [[Texture Folder Structure]]
* [[Basic Material File]]

== Links ==

=== Photoshop ===

* [http://developer.nvidia.com/object/photoshop_dds_plugins.html nVidia Normal Map PlugIn]

=== Gimp ===

* [http://nifelheim.dyndns.org/~cocidius/normalmap/ GIMP normalmap plugin]
* [http://www.manucornet.net/Informatique/Texturize.php#download GIMP texturize plugin *THIS IS AMAZING*]
* [http://registry.gimp.org/plugin?id=4816 Gimp DDS plugin]

=== Assorted tutorials ===

* [http://www.doom3world.org/phpbb2/viewtopic.php?t=11893 Doom3World texture tutorials]
* [http://www.quake3bits.com/htm/tutorials/creating_bumpmaps_from_images.htm Kat's normal-map making tutorial]
* [http://www.gimp.org/tutorials/Tileable_Textures/ Quick GIMP tutorial for tileable textures]
* [http://www.stormvision.net/index.cfm/act/tutorials/tutorial_ID/1 Another tileable texture tutorial]

How to add Textures to The Dark Mod

2016-05-21T08:28:49Z

Demagogue: /* Move the Texture to the right Location */

== Create your texture ==
This is mostly artwork. Be sure to start off with useful raw material with a reasonably high resolution. Where possible, work from photo-references. A basic guide can be found here: [[Texture Creation - Basic Tutorial]].

A few things to remember: Make sure your texture dimensions are a power of 2 (eg, 128, 256, 512, 1024, etc). Other common mistakes can be found here: [[Common Texture Mistakes]]
{{Things-To-Remember|
* Use good source material
* All image dimensions must be powers of two: 64, 128, 256, 512, 1024 (don't go beyond 1024).
* Avoid lighting baked into the diffusemap
* Keep your PSD/Gimp working version safe!}}
== Save your Texture in the correct Format ==
Save the diffusemap, the normalmap and an optional specularmap to a TGA file. The '''[[Texture Guidelines]]''' will help you choosing the correct resolution. A TGA version of your diffusemap is supposed to be uploaded to our hi-res repository for future reference (see below).

Once your TGA file is saved, you will have to create DDS files for the diffuse and specular (not the normalmap) as well. These are smaller in size and can be loaded faster by the engine. Follow the '''[[DDS creation]]''' guide to learn how to create the DDS files in the correct formats.

Also, create an editor image out of your diffusemap. The editor image dimension should be 256x256 pixels and the file should be saved in the JPG format. Add the '''_ed''' postfix to the filename name (like <code>mytexture_ed.jpg</code>).
{{Things-To-Remember|
* Most textures don't need speculars
* Create DDS for your diffusemap and specularmap.
* Keep TGA version of your diffusemap and specularmap.
* Create a TGA version of your normalmap (uncompressed, no RLE).
* Create a JPG editor image (max. 256px)}}
== Name your Texture ==
The following convention should be used for naming all new texture additions to TDM (many existing textures do not follow this convention, and over time effort will be made to update them). The goal is consistency among material names based on ordered characteristics.

'''Some or all''' of the following may apply to any given material:

# '''Object Type''' descriptor first (mostly for very specific-use textures) - it's a window, a door, a chest...
# '''Material''' descriptor next - made from marble, wood, mud...
# '''Size''' descriptor next - it is large, small...
# '''Quality''' descriptors next - texture-wise, it is rough, new, cracked...
# '''Color''' descriptors next - what color is it? red, green...
# '''Number Increment''' next - which of the list is it? 001, 002...
# '''Tiling''' and '''Image Type''' descriptors, if needed (file only, not material definition - see below)

If establishing precedent (creating a new '''Size''' descriptor, e.g., "huge"), try to avoid ambiguity and unnecessary overlapping with other descriptors (e.g., "enormous"), and set a good example others will follow.

'''Examples:'''

1. ''slate_large_cracked_grey_001''

This name omits an '''Object Type''' descriptor, instead starting with the '''Material''' descriptor - it is a general, non-specialized texture.

Why is this preferred? Some existing materials are named by quality descriptor first (e.g., 'cracked_slate...'). This is an inconvenience for the user, because they were looking for a 'slate', not a 'cracked'.

2. ''door_wood_battered_005''

This name omits a '''Size''' descriptor and a '''Color''' descriptor.

Why is this preferred? In the case of a model name (which this convention also covers), or a specific object type texture like the above, some existing assets are named by quality descriptor first (e.g., 'battered_wood...'). This is an inconvenience for the user, because they were looking for a 'door', not a 'battered'.

Be sure to rename all your DDS file extensions to a '''lowercase''' '''.dds''' (the Compressonator always creates files with uppercase extension, TDM requires them to be lowercase).

If your texture tiles only in one direction, include the phrase '''tiling_1d''' at the end of the name. If your texture does not tile (repeat) at all, add the phrase '''nontiling'''. So, a normalmap could be names as '''concrete_dirt01_tiling1d_local.tga'''.

Diffusemaps should have no extension to their name. Normalmaps should have a '''_local''' extension at the end of their name. Specular maps should have a '''_s''' extension, the editor images go with an '''_ed''' extension.
{{Things-To-Remember|
* Choose descriptive names for your texture, while following TDM convention
* Add the suffix '''tiling_1d'''/'''nontiling''' to the filename where appropriate
* Diffusemap: '''mytexture.dds''' (note the '''lowercase''')
* Normalmap: '''mytexture_local.tga'''
* Editor image: '''mytexture_ed.jpg''' (max. 256 pixels in size)
* (Optional) Specularmap: '''mytexture_s.dds'''}}

== Move the Texture to the right Location ==
When you upload textures, be sure to upload the files to the right spot. The '''[[Texture Folder Structure]]''' can help you finding the right folder for your texture.

The .dds diffuse and specular go in the '''dds/textures/''' folder structure. The .tga normalmap goes in the '''textures/''' folder structure. Also, the texture may not render properly unless it's nested inside "../textures/darkmod/" and for a custom texture (only for FM use) you can have "../textures/darkmod/your_texture_folder" in both the parent Darkmod folder and inside your pk4. Note that there is a peculiarity of the Doom 3 engine not being able to load DDS textures that are more than five folders deep. The deepest level allowed would be something along the lines of dds/textures/darkmod/door/metal/. This is something to be watched out for.
{{Things-To-Remember|
* Move the DDS textures into the '''dds/textures/...''' tree.
* Move the TGA and JPG files into the '''textures/...''' tree.
* Don't save DDS files into folders more than 5 levels deep.}}

== Create your Shader Definition (Material) ==
Your material entry should be added to the .mtr file that has the same name as the folder your texture is saved in. For example, the material entry for a texture saved in '''textures/darkmod/wood/panels''' should be saved in the .mtr file, '''tdm_wood_panels.mtr'''. See also the [[Material File Naming Convention]].

You should name your material entry the same name as your diffuse texture, including the folder path structure (eg, "textures/darkmod/wood/panels/rectangle_oak_face"). (Do not add .tga or .dds to the end, and also skip the dds/ folder prefix.)

The only exception is when multiple shaders are using the same diffusemap, or when your texture doesn't tile (or tiles in only one direction). In the latter case, you would add '''/nontiling/''' or "/tiling_1d/''' to the end of the shader folder (a 'virtual' folder, essentially). ''(The textures used to be separated like that in the actual folder structure, but due to D3's inability to read .dds files five folders deep, they had to be moved.)''
{{Things-To-Remember|
* Create your shader in the correct file (tdm_xxx_yyy.mtr) following the [[Material File Naming Convention]]
* The shader name for tiling textures is the same as the diffusemap
* Nontiling/tiling_1d textures go into a "virtual" subfolder nontiling/ or tiling_1d/
* You don't need to specify file extensions (.dds/.tga/.jpg) to the material defs, this is automatically guessed by the engine.
* You don't need the '''dds/''' folder prefix to reference the DDS textures.
* Be sure to include the frob highlight code (see [[Basic Material File#Add_the_Frob_Highlight_Stage|Basic Material File]])
* You '''must''' include Dark Mod's ambient light stage (see [[Virtual Ambient Light Textures]])}}

== Upload the Textures ==
Once, you have checked your texture in-game (and are pleased with the results), you'll need to upload the files to our SVN repository. This requires that you have a valid username/password for SVN, which you can request from sparhawk.

The .tga of the diffuse and specular is needed as well in case we ever want to make modifications to the texture or new textures based on the old. Opening and resaving .dds files results in loss of detail, so all new versions of textures should be made from the .tga files. So, additional to the textures needed for the engine and editor (diffuse/normal/specular/editorimage) you're encouraged to upload the uncompressed textures to the hires repository.

The hires repository is located at '''<nowiki>https://<InsertDarkmodServerHere>/svn/darkmod_hires/trunk/tga_backup/</nowiki>'''. As only diffuse/speculars are compressed in DDS format, these are the only two that need to be uploaded in TGA format. The TGA files should be named just like the DDS versions and should be located in the analogous folder than they are in the main repository, but below the tga_backup/ folder. For instance tga_backup/textures/darkmod/stone/etc.

The hires TGA can be RLE-compressed to save some space, but this is not too important. Uncompressed TGAs are only important for the textures used by the engine itself.

As last part, it would be nice to have the actual working versions (Photoshop/Gimp source files) stored on the server too. This is of course a large upload, but having the source files is very valuable. For this purpose, there is another repository '''texture_src''' installed at '''<nowiki>https://<InsertDarkmodServerHere>/svn/texture_src/</nowiki>'''.
{{Things-To-Remember|
* Upload the diffuse, normal, (specular,) and editor image to the regular darkmod SVN.
* Upload the (RLE-compressed) TGA diffusemap and specularmap to the darkmod_hires SVN repository (into the '''tga_backup''' subfolder).
* Upload the working source file (PSD/Gimp) to the '''texture_src''' repository.}}
{{tutorial-textures}}
__NOTOC__

How to add Textures to The Dark Mod

2016-05-21T08:28:11Z

Demagogue: /* Move the Texture to the right Location */

== Create your texture ==
This is mostly artwork. Be sure to start off with useful raw material with a reasonably high resolution. Where possible, work from photo-references. A basic guide can be found here: [[Texture Creation - Basic Tutorial]].

A few things to remember: Make sure your texture dimensions are a power of 2 (eg, 128, 256, 512, 1024, etc). Other common mistakes can be found here: [[Common Texture Mistakes]]
{{Things-To-Remember|
* Use good source material
* All image dimensions must be powers of two: 64, 128, 256, 512, 1024 (don't go beyond 1024).
* Avoid lighting baked into the diffusemap
* Keep your PSD/Gimp working version safe!}}
== Save your Texture in the correct Format ==
Save the diffusemap, the normalmap and an optional specularmap to a TGA file. The '''[[Texture Guidelines]]''' will help you choosing the correct resolution. A TGA version of your diffusemap is supposed to be uploaded to our hi-res repository for future reference (see below).

Once your TGA file is saved, you will have to create DDS files for the diffuse and specular (not the normalmap) as well. These are smaller in size and can be loaded faster by the engine. Follow the '''[[DDS creation]]''' guide to learn how to create the DDS files in the correct formats.

Also, create an editor image out of your diffusemap. The editor image dimension should be 256x256 pixels and the file should be saved in the JPG format. Add the '''_ed''' postfix to the filename name (like <code>mytexture_ed.jpg</code>).
{{Things-To-Remember|
* Most textures don't need speculars
* Create DDS for your diffusemap and specularmap.
* Keep TGA version of your diffusemap and specularmap.
* Create a TGA version of your normalmap (uncompressed, no RLE).
* Create a JPG editor image (max. 256px)}}
== Name your Texture ==
The following convention should be used for naming all new texture additions to TDM (many existing textures do not follow this convention, and over time effort will be made to update them). The goal is consistency among material names based on ordered characteristics.

'''Some or all''' of the following may apply to any given material:

# '''Object Type''' descriptor first (mostly for very specific-use textures) - it's a window, a door, a chest...
# '''Material''' descriptor next - made from marble, wood, mud...
# '''Size''' descriptor next - it is large, small...
# '''Quality''' descriptors next - texture-wise, it is rough, new, cracked...
# '''Color''' descriptors next - what color is it? red, green...
# '''Number Increment''' next - which of the list is it? 001, 002...
# '''Tiling''' and '''Image Type''' descriptors, if needed (file only, not material definition - see below)

If establishing precedent (creating a new '''Size''' descriptor, e.g., "huge"), try to avoid ambiguity and unnecessary overlapping with other descriptors (e.g., "enormous"), and set a good example others will follow.

'''Examples:'''

1. ''slate_large_cracked_grey_001''

This name omits an '''Object Type''' descriptor, instead starting with the '''Material''' descriptor - it is a general, non-specialized texture.

Why is this preferred? Some existing materials are named by quality descriptor first (e.g., 'cracked_slate...'). This is an inconvenience for the user, because they were looking for a 'slate', not a 'cracked'.

2. ''door_wood_battered_005''

This name omits a '''Size''' descriptor and a '''Color''' descriptor.

Why is this preferred? In the case of a model name (which this convention also covers), or a specific object type texture like the above, some existing assets are named by quality descriptor first (e.g., 'battered_wood...'). This is an inconvenience for the user, because they were looking for a 'door', not a 'battered'.

Be sure to rename all your DDS file extensions to a '''lowercase''' '''.dds''' (the Compressonator always creates files with uppercase extension, TDM requires them to be lowercase).

If your texture tiles only in one direction, include the phrase '''tiling_1d''' at the end of the name. If your texture does not tile (repeat) at all, add the phrase '''nontiling'''. So, a normalmap could be names as '''concrete_dirt01_tiling1d_local.tga'''.

Diffusemaps should have no extension to their name. Normalmaps should have a '''_local''' extension at the end of their name. Specular maps should have a '''_s''' extension, the editor images go with an '''_ed''' extension.
{{Things-To-Remember|
* Choose descriptive names for your texture, while following TDM convention
* Add the suffix '''tiling_1d'''/'''nontiling''' to the filename where appropriate
* Diffusemap: '''mytexture.dds''' (note the '''lowercase''')
* Normalmap: '''mytexture_local.tga'''
* Editor image: '''mytexture_ed.jpg''' (max. 256 pixels in size)
* (Optional) Specularmap: '''mytexture_s.dds'''}}

== Move the Texture to the right Location ==
When you upload textures, be sure to upload the files to the right spot. The '''[[Texture Folder Structure]]''' can help you finding the right folder for your texture.

The .dds diffuse and specular go in the '''dds/textures/''' folder structure. The .tga normalmap goes in the '''textures/''' folder structure. Also, the texture may not render properly unless it's nested inside "../textures/darkmod/" and for a custom texture (only for FM use) you can have " "../textures/darkmod/your_texture_folder" in both the parent Darkmod folder and inside your pk4. Note that there is a peculiarity of the Doom 3 engine not being able to load DDS textures that are more than five folders deep. The deepest level allowed would be something along the lines of dds/textures/darkmod/door/metal/. This is something to be watched out for.
{{Things-To-Remember|
* Move the DDS textures into the '''dds/textures/...''' tree.
* Move the TGA and JPG files into the '''textures/...''' tree.
* Don't save DDS files into folders more than 5 levels deep.}}

== Create your Shader Definition (Material) ==
Your material entry should be added to the .mtr file that has the same name as the folder your texture is saved in. For example, the material entry for a texture saved in '''textures/darkmod/wood/panels''' should be saved in the .mtr file, '''tdm_wood_panels.mtr'''. See also the [[Material File Naming Convention]].

You should name your material entry the same name as your diffuse texture, including the folder path structure (eg, "textures/darkmod/wood/panels/rectangle_oak_face"). (Do not add .tga or .dds to the end, and also skip the dds/ folder prefix.)

The only exception is when multiple shaders are using the same diffusemap, or when your texture doesn't tile (or tiles in only one direction). In the latter case, you would add '''/nontiling/''' or "/tiling_1d/''' to the end of the shader folder (a 'virtual' folder, essentially). ''(The textures used to be separated like that in the actual folder structure, but due to D3's inability to read .dds files five folders deep, they had to be moved.)''
{{Things-To-Remember|
* Create your shader in the correct file (tdm_xxx_yyy.mtr) following the [[Material File Naming Convention]]
* The shader name for tiling textures is the same as the diffusemap
* Nontiling/tiling_1d textures go into a "virtual" subfolder nontiling/ or tiling_1d/
* You don't need to specify file extensions (.dds/.tga/.jpg) to the material defs, this is automatically guessed by the engine.
* You don't need the '''dds/''' folder prefix to reference the DDS textures.
* Be sure to include the frob highlight code (see [[Basic Material File#Add_the_Frob_Highlight_Stage|Basic Material File]])
* You '''must''' include Dark Mod's ambient light stage (see [[Virtual Ambient Light Textures]])}}

== Upload the Textures ==
Once, you have checked your texture in-game (and are pleased with the results), you'll need to upload the files to our SVN repository. This requires that you have a valid username/password for SVN, which you can request from sparhawk.

The .tga of the diffuse and specular is needed as well in case we ever want to make modifications to the texture or new textures based on the old. Opening and resaving .dds files results in loss of detail, so all new versions of textures should be made from the .tga files. So, additional to the textures needed for the engine and editor (diffuse/normal/specular/editorimage) you're encouraged to upload the uncompressed textures to the hires repository.

The hires repository is located at '''<nowiki>https://<InsertDarkmodServerHere>/svn/darkmod_hires/trunk/tga_backup/</nowiki>'''. As only diffuse/speculars are compressed in DDS format, these are the only two that need to be uploaded in TGA format. The TGA files should be named just like the DDS versions and should be located in the analogous folder than they are in the main repository, but below the tga_backup/ folder. For instance tga_backup/textures/darkmod/stone/etc.

The hires TGA can be RLE-compressed to save some space, but this is not too important. Uncompressed TGAs are only important for the textures used by the engine itself.

As last part, it would be nice to have the actual working versions (Photoshop/Gimp source files) stored on the server too. This is of course a large upload, but having the source files is very valuable. For this purpose, there is another repository '''texture_src''' installed at '''<nowiki>https://<InsertDarkmodServerHere>/svn/texture_src/</nowiki>'''.
{{Things-To-Remember|
* Upload the diffuse, normal, (specular,) and editor image to the regular darkmod SVN.
* Upload the (RLE-compressed) TGA diffusemap and specularmap to the darkmod_hires SVN repository (into the '''tga_backup''' subfolder).
* Upload the working source file (PSD/Gimp) to the '''texture_src''' repository.}}
{{tutorial-textures}}
__NOTOC__

How to add Textures to The Dark Mod

2016-05-21T08:26:29Z

Demagogue: /* Move the Texture to the right Location */

== Create your texture ==
This is mostly artwork. Be sure to start off with useful raw material with a reasonably high resolution. Where possible, work from photo-references. A basic guide can be found here: [[Texture Creation - Basic Tutorial]].

A few things to remember: Make sure your texture dimensions are a power of 2 (eg, 128, 256, 512, 1024, etc). Other common mistakes can be found here: [[Common Texture Mistakes]]
{{Things-To-Remember|
* Use good source material
* All image dimensions must be powers of two: 64, 128, 256, 512, 1024 (don't go beyond 1024).
* Avoid lighting baked into the diffusemap
* Keep your PSD/Gimp working version safe!}}
== Save your Texture in the correct Format ==
Save the diffusemap, the normalmap and an optional specularmap to a TGA file. The '''[[Texture Guidelines]]''' will help you choosing the correct resolution. A TGA version of your diffusemap is supposed to be uploaded to our hi-res repository for future reference (see below).

Once your TGA file is saved, you will have to create DDS files for the diffuse and specular (not the normalmap) as well. These are smaller in size and can be loaded faster by the engine. Follow the '''[[DDS creation]]''' guide to learn how to create the DDS files in the correct formats.

Also, create an editor image out of your diffusemap. The editor image dimension should be 256x256 pixels and the file should be saved in the JPG format. Add the '''_ed''' postfix to the filename name (like <code>mytexture_ed.jpg</code>).
{{Things-To-Remember|
* Most textures don't need speculars
* Create DDS for your diffusemap and specularmap.
* Keep TGA version of your diffusemap and specularmap.
* Create a TGA version of your normalmap (uncompressed, no RLE).
* Create a JPG editor image (max. 256px)}}
== Name your Texture ==
The following convention should be used for naming all new texture additions to TDM (many existing textures do not follow this convention, and over time effort will be made to update them). The goal is consistency among material names based on ordered characteristics.

'''Some or all''' of the following may apply to any given material:

# '''Object Type''' descriptor first (mostly for very specific-use textures) - it's a window, a door, a chest...
# '''Material''' descriptor next - made from marble, wood, mud...
# '''Size''' descriptor next - it is large, small...
# '''Quality''' descriptors next - texture-wise, it is rough, new, cracked...
# '''Color''' descriptors next - what color is it? red, green...
# '''Number Increment''' next - which of the list is it? 001, 002...
# '''Tiling''' and '''Image Type''' descriptors, if needed (file only, not material definition - see below)

If establishing precedent (creating a new '''Size''' descriptor, e.g., "huge"), try to avoid ambiguity and unnecessary overlapping with other descriptors (e.g., "enormous"), and set a good example others will follow.

'''Examples:'''

1. ''slate_large_cracked_grey_001''

This name omits an '''Object Type''' descriptor, instead starting with the '''Material''' descriptor - it is a general, non-specialized texture.

Why is this preferred? Some existing materials are named by quality descriptor first (e.g., 'cracked_slate...'). This is an inconvenience for the user, because they were looking for a 'slate', not a 'cracked'.

2. ''door_wood_battered_005''

This name omits a '''Size''' descriptor and a '''Color''' descriptor.

Why is this preferred? In the case of a model name (which this convention also covers), or a specific object type texture like the above, some existing assets are named by quality descriptor first (e.g., 'battered_wood...'). This is an inconvenience for the user, because they were looking for a 'door', not a 'battered'.

Be sure to rename all your DDS file extensions to a '''lowercase''' '''.dds''' (the Compressonator always creates files with uppercase extension, TDM requires them to be lowercase).

If your texture tiles only in one direction, include the phrase '''tiling_1d''' at the end of the name. If your texture does not tile (repeat) at all, add the phrase '''nontiling'''. So, a normalmap could be names as '''concrete_dirt01_tiling1d_local.tga'''.

Diffusemaps should have no extension to their name. Normalmaps should have a '''_local''' extension at the end of their name. Specular maps should have a '''_s''' extension, the editor images go with an '''_ed''' extension.
{{Things-To-Remember|
* Choose descriptive names for your texture, while following TDM convention
* Add the suffix '''tiling_1d'''/'''nontiling''' to the filename where appropriate
* Diffusemap: '''mytexture.dds''' (note the '''lowercase''')
* Normalmap: '''mytexture_local.tga'''
* Editor image: '''mytexture_ed.jpg''' (max. 256 pixels in size)
* (Optional) Specularmap: '''mytexture_s.dds'''}}

== Move the Texture to the right Location ==
When you upload textures, be sure to upload the files to the right spot. The '''[[Texture Folder Structure]]''' can help you finding the right folder for your texture.

The .dds diffuse and specular go in the '''dds/textures/''' folder structure. The .tga normalmap goes in the '''textures/''' folder structure. Also, the texture may not render properly unless it's nested inside "../textures/darkmod/" and for a custom texture you can have " "../textures/darkmod/your_texture_folder". Note that there is a peculiarity of the Doom 3 engine not being able to load DDS textures that are more than five folders deep. The deepest level allowed would be something along the lines of dds/textures/darkmod/door/metal/. This is something to be watched out for.
{{Things-To-Remember|
* Move the DDS textures into the '''dds/textures/...''' tree.
* Move the TGA and JPG files into the '''textures/...''' tree.
* Don't save DDS files into folders more than 5 levels deep.}}

== Create your Shader Definition (Material) ==
Your material entry should be added to the .mtr file that has the same name as the folder your texture is saved in. For example, the material entry for a texture saved in '''textures/darkmod/wood/panels''' should be saved in the .mtr file, '''tdm_wood_panels.mtr'''. See also the [[Material File Naming Convention]].

You should name your material entry the same name as your diffuse texture, including the folder path structure (eg, "textures/darkmod/wood/panels/rectangle_oak_face"). (Do not add .tga or .dds to the end, and also skip the dds/ folder prefix.)

The only exception is when multiple shaders are using the same diffusemap, or when your texture doesn't tile (or tiles in only one direction). In the latter case, you would add '''/nontiling/''' or "/tiling_1d/''' to the end of the shader folder (a 'virtual' folder, essentially). ''(The textures used to be separated like that in the actual folder structure, but due to D3's inability to read .dds files five folders deep, they had to be moved.)''
{{Things-To-Remember|
* Create your shader in the correct file (tdm_xxx_yyy.mtr) following the [[Material File Naming Convention]]
* The shader name for tiling textures is the same as the diffusemap
* Nontiling/tiling_1d textures go into a "virtual" subfolder nontiling/ or tiling_1d/
* You don't need to specify file extensions (.dds/.tga/.jpg) to the material defs, this is automatically guessed by the engine.
* You don't need the '''dds/''' folder prefix to reference the DDS textures.
* Be sure to include the frob highlight code (see [[Basic Material File#Add_the_Frob_Highlight_Stage|Basic Material File]])
* You '''must''' include Dark Mod's ambient light stage (see [[Virtual Ambient Light Textures]])}}

== Upload the Textures ==
Once, you have checked your texture in-game (and are pleased with the results), you'll need to upload the files to our SVN repository. This requires that you have a valid username/password for SVN, which you can request from sparhawk.

The .tga of the diffuse and specular is needed as well in case we ever want to make modifications to the texture or new textures based on the old. Opening and resaving .dds files results in loss of detail, so all new versions of textures should be made from the .tga files. So, additional to the textures needed for the engine and editor (diffuse/normal/specular/editorimage) you're encouraged to upload the uncompressed textures to the hires repository.

The hires repository is located at '''<nowiki>https://<InsertDarkmodServerHere>/svn/darkmod_hires/trunk/tga_backup/</nowiki>'''. As only diffuse/speculars are compressed in DDS format, these are the only two that need to be uploaded in TGA format. The TGA files should be named just like the DDS versions and should be located in the analogous folder than they are in the main repository, but below the tga_backup/ folder. For instance tga_backup/textures/darkmod/stone/etc.

The hires TGA can be RLE-compressed to save some space, but this is not too important. Uncompressed TGAs are only important for the textures used by the engine itself.

As last part, it would be nice to have the actual working versions (Photoshop/Gimp source files) stored on the server too. This is of course a large upload, but having the source files is very valuable. For this purpose, there is another repository '''texture_src''' installed at '''<nowiki>https://<InsertDarkmodServerHere>/svn/texture_src/</nowiki>'''.
{{Things-To-Remember|
* Upload the diffuse, normal, (specular,) and editor image to the regular darkmod SVN.
* Upload the (RLE-compressed) TGA diffusemap and specularmap to the darkmod_hires SVN repository (into the '''tga_backup''' subfolder).
* Upload the working source file (PSD/Gimp) to the '''texture_src''' repository.}}
{{tutorial-textures}}
__NOTOC__

Texture Creation - Basic Tutorial

2016-05-21T08:21:31Z

Demagogue: /* Create your material file */

{{tutorial-textures}} {{Original_Reference|SneaksieDave|3814}}
A game like this needs a TON of textures. So I wanted to try to learn how to do this mysterious, wonderous, magick...

Erm, well, it's not magick. Far from it, in fact. This tutorial isn't for those of you who already know how to do this*, and already know it's not magick. This tutorial is for the rest of us, those who have been too scared or lazy to even bother asking "how do I?", like me. (It's the former, honest!)

== Prerequisites ==

You can use Gimp or Photoshop on Windows, for Linux you should use Gimp. So you'll need either of the two programs Gimp/Photoshop and the corresponding set of plugins:

=== Photoshop ===

* [http://developer.nvidia.com/object/photoshop_dds_plugins.html Nvidia normal map plugin]

=== Gimp ===

* [http://code.google.com/p/gimp-normalmap/#Download GIMP normalmap plugin]
* [http://gimp-texturize.sourceforge.net/download.html GIMP texturize plugin]
* [http://code.google.com/p/gimp-dds/ Gimp DDS plugin]

If you are using Kubuntu/Ubuntu, you can also install the <code>gimp-texturize</code> and <code>gimp-resynthesizer</code> packages.

To compile Gimp plugins from source, install the following packages and their dependecies:

* libgimp2.0-dev
* libgtk1.2-dev
* libglut3-dev (for the DDS plugin)

== Get your source picture ==

This could be anything from a photograph you took, to a free texture download from the internet (see [[Texture Sources]]), to a hand drawn picture, if you're one of those fortunate enough to possess that skill - though we generally prefer to work from photo-reference when possible.

If you do want to take photos, some tips:
* try to shoot on an overcast day; the diffuse light will remove most unwanted shadows
* try to take the photo as perfectly face-on to the surface as you can manage.
If your end result isn't perfect, don't worry, there are ways to fix it (transform->skew, to name one)
* Make sure that all parts of your photo you want to use as texture are in focus (e.g. sharp). Unsharp parts cannot be fixed later, at least not without a big quality loss!
* try to select an area that will be tile-able (if that's what you want)
* try to capture a large area such that you'll have enough to work with, but not so big that your resolution on the final product will suffer

== Create the diffuse map ==

The diffuse map is a tilable (usally) image which gives the color infomation, but does not contain lighting or height information for the texture. It is stored as dds with dxt1 or dxt3 compression for use in Doom 3 and as 24 bit TGA (with or without RLE) for the hires repository.

If your image has lighting baked in (shadows/highlights), you should remove it: [[Remove Shadows in Source Images]].

This is just a basic tutorial for creating textures. For further information about creating Diffusemaps, read [[Advanced Tips for Creating Diffusemaps]].

=== Photoshop ===

Inspect the source image. If you're going to tile it, try to find a regular repeating area. This is only to make your job easier. You can tile anything, really, but it depends on how much work you want to give yourself. If you don't know what I mean here, at the next step you will.

After you've chosen a rough tile-able area (from here forward I'm going to assume you are doing a tiled texture), crop that area out, and size your image to the desired size ratio. I wouldn't go lower than 1024 resolution at this stage of the work, or you'll start losing picture quality quickly. So set it to 2048X1024, or 1024X1024, etc. The reason we need to fix the size ratio (not the final size) at this stage is for the next step.

==== Set the offset ====

Go to Filter->Other->Offset. You want to set the horizontal and vertical to be exactly half of your cropped picture's width and height. That will make the opposite edges of the texture meet each other in the middle of the view, so you can make it really tile-able.

==== Make the seams disappear ====
See those seams running right down the middle of the pic, vertically and horizontally? You have to make them disappear. Get to know the clone tool. (Google...) There are many other ways to shuffle pixels too, but I'll leave the specifics up to you. This is usually the hardest, most time consuming step.

Once you've blended the lines away, run the Offset filter again to restore the correct layout of your pic, and save it out in a nice high quality (but not too big to manage) format. This is the "diffuse" image. We're using 24bit TGA for TDM.

=== Gimp ===

Use the <code>texturizer</code> or the <code>resynthezier</code> plugin - these are very easy to work with and make manual work almost needless.

== Create a normal map ==

The Normalmap tells the renderer in which direction a corresponding place on the diffusemap is facing, so that it can be shaded according to the present lightsources in the scene. It is stored as uncompressed 24 bit TGA (no RLE!) for use in Doom 3. You will learn the basics about creating Normalmaps here. For further information: [[Normalmaps, How to Make Good Ones]].

=== Photoshop ===

Now that the diffuse is done, using that same pic, open Filter->Nvidia Tools->NormalMapFilter. You'll probably have to play with the values for a while to get a feel for it, and to get a normal map you are happy with. This is a rough approximation method, by no means as accurate as actually modelling a texture (see [[Wall Texture Tutorial]] or [[Creating Textures with Normals out of Models]]), but it works pretty good in most cases. Basically, it will make light areas "high" and dark areas "low". Learn how to manipulate color levels in Photoshop, and you'll be making good normal maps with the Nvidia filter in no time. Generally, use values of 3 or 4 for simple things like woodgrain or nails. Values of 12 or higher can be used for more 3d effects.

If you think about it, there are countless ways to adjust the image (in fact, you're not even restricted to using the diffuse image as the base of the normal map...) to get desired results - inverting colors, brightness and contrast controls, painting over areas, gradients, etc. It's a "feel" thing, so you'll have to develop that for yourself. After creating your desired normal map (try not to make it too blurry, or too sharp, or too bumpy - yuck), save it out as you did with the diffuse image, with "_local" appended.

=== Gimp ===

This is a rough guide by a non-expert as I (fidcal) do it so at least there is something here. It assumes you have made a temporary greyscale image file saved as say nameGrey.tga with the brighter areas representing the high ground and darker means low as described elsewhere ready to make your make normal map. It assumes you've just downloaded Gimp and its Normalmap plugin (ESSENTIAL!), maybe configured it a bit so don't know much about it but just want a dumb list to follow.

* Open Gimp
* Gimp consists of separate floating windows with no main window so select the toolbar window > file menu > and open your greyscale image file.
* You can enlarge/maximize the window and zoom with the mouse wheel if you want.
* Menu > filters > map > normalmap
* On the normal map dialog, Click 3D map preview; it will make more sense then.
* On the normal map dialog, in the 'scale' box there is zero by default which is useless as a default as this seems to be the scale of depth. Enter 50 for a start.
* On the 3D preview dialog there is a window with a panel in it. Grab the panel with your left mouse button and drag it around. Now you should see a rough 3D impression of your image.
* If you have no idea what you're doing (like me) leave the scale at 50 as a reasonable value, otherwise adjust it according to your knowledge. Maybe come back here later if you feel your final result is not deep enough or too deep. Similarly leave the other controls or adjust if you know what you are doing.
* On the normal map dialog click OK.
* On Gimp's image window you should now see your greyscale image has been converted probably blue looking with depressions, eg inverted the heights; that's OK.
* Save as name_local.tga in the correct dark mod texture folder where your main texture is.
* A mini dialog pops up : RLE compression - set this UNchecked, and 'origin at bottom left' - leave this checked. Click OK.
* I had a lot of programs open including Doom so it seemed to hang a long time but eventually saved.
* You close Gimp by closing that toolbar window so I guess that's its nearest thing to a main window.

That's it.

== Create an editor image ==
As the diffusemap is very large it takes some time loading it into the editor, this is why DarkRadiant/DoomEd support the display of lowres editor images replacements. Just resize the diffusemap down to max. 256 pixels and save it in JPG format, but be sure to attach the '''_ed''' suffix.

== Add a specular map ==
The specularmap tells the renderer how shiny a corresponding place on the diffusemap is. It is stored as dds and its dimensions are typically scaled down to be half as big as those of the diffusemap.

If you want a specular map, the process is even more subjective. There are countless ways in Photoshop to adjust color and light level and even invert everything or parts or mask out areas. Specular maps work as such: Darker is rendered as dull, lighter is rendered as shiny. Get it? Think of the possibilities, and have fun with it. You can get some pretty amazing results with just minutes of work. Save that image out as you did the diffuse, '''with "_s" appended'''.

Note that most surface types don't need a specular map. Only shiny surfaces, like metal or wet stone, really need one, while wood, cobbles, canvas, leaves, dirt etc. should not have a specular map.

== Create your material file ==

Create a material for the texture (see [[Basic Material File]]). In the materials folder, locate the material file where you texture fits in best. Then add the following:

(Note: My texture didn't render properly unless I nested it inside "textures/darkmod/your_texture_folder".)

<pre>
textures/your_desired_editor_texture_folder/your_texture_name
{
// Use one of the predefined surface types like stone, glass, wood
stone
// or use this:
// surfaceType 15
// and make the first word in the description below your texture type,
// like so:
// description "foliage" (This is a grass texture)

description "Add here a little description of your texture"
qer_editorimage textures/your_file_folder/your_texture_name_ed

bumpmap textures/your_file_folder/your_texture_name_local
diffusemap textures/your_file_folder/your_texture_name
specularmap textures/your_file_folder/your_texture_name_s

// This is the code required for frob highlighting this texture
{
if ( parm11 > 0 )
blend gl_dst_color, gl_one
map _white.tga
rgb 0.40 * parm11
}
{
if ( parm11 > 0 )
blend add
map textures/your_file_folder/your_texture_name
rgb 0.15 * parm11
}

// The following two blocks are required for the ambient shading:
// TDM Ambient Method Related
{
if (global5 == 1)
blend add
map textures/your_file_folder/your_texture_name
scale 1, 1
red global2
green global3
blue global4
}
{
if (global5 == 2)
blend add
program ambientEnvironment.vfp
vertexParm 0 1, 1, 1, 1 // UV Scales for Diffuse and Bump
vertexParm 1 1, 1, 1, 1 // (X,Y) UV Scale for specular
vertexParm 2 global2, global3, global4, 1

fragmentMap 0 cubeMap env/gen1
fragmentMap 1 textures/your_file_folder/your_texture_name_local // Bump
fragmentMap 2 textures/your_file_folder/your_texture_name // Diffuse
fragmentMap 3 _black // Specular
}
}
</pre>

Oh, and on Windows, use Wordpad, not Notepad. That's it. Your new texture should appear in both the editor and in-game.

== Summary ==
So you see, it's really quite simple:
* Crop the desired area
* Make it tileable if necessary
* Generate a normal map
* Generate an editor image
* Create a specular map if you want one
* Include it in a material file
* DONE

The most important thing though, is to obey the [[Texture Guidelines]].

== Further Information ==

* [[Common Texture Mistakes]]
* [[How to add Textures to The Dark Mod]]
* [[Texture Folder Structure]]
* [[Basic Material File]]

== Links ==

=== Photoshop ===

* [http://developer.nvidia.com/object/photoshop_dds_plugins.html nVidia Normal Map PlugIn]

=== Gimp ===

* [http://nifelheim.dyndns.org/~cocidius/normalmap/ GIMP normalmap plugin]
* [http://www.manucornet.net/Informatique/Texturize.php#download GIMP texturize plugin *THIS IS AMAZING*]
* [http://registry.gimp.org/plugin?id=4816 Gimp DDS plugin]

=== Assorted tutorials ===

* [http://www.doom3world.org/phpbb2/viewtopic.php?t=11893 Doom3World texture tutorials]
* [http://www.quake3bits.com/htm/tutorials/creating_bumpmaps_from_images.htm Kat's normal-map making tutorial]
* [http://www.gimp.org/tutorials/Tileable_Textures/ Quick GIMP tutorial for tileable textures]
* [http://www.stormvision.net/index.cfm/act/tutorials/tutorial_ID/1 Another tileable texture tutorial]

Location Settings

2016-03-08T10:50:34Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, or for reading a book, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix mentioned above, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. If you open the console, it will report that the override ambient is playing. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop. Using the function sys.waitFor( $[speaker_name]); after running the speaker is supposed to automatically wait the duration, but this needs to be tested.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $tdm_location_settings_1.setKey( "override", "[snd_name]"); to turn on an override sound and $[tls_1].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas. Also be sure to use the right name for the location settings entity. It may not have a "_1" suffix.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "tdm_location_settings_1"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. (Volume is not included however. You'd just use the speaker property "s_volume" directly, but you'd need to restore it after the override is over if you don't want the change applying to all sounds.) You can change them dynamically in the same way as override. If you have multiple overrides, some with fading and some without, and want to revert to the default fading without looking it up, you can enter "-1" as the value of a property and it uses the default value.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-14T04:56:20Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, or for reading a book, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix mentioned above, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. If you open the console, it will report that the override ambient is playing. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $tdm_location_settings_1.setKey( "override", "[snd_name]"); to turn on an override sound and $[tls_1].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas. Also be sure to use the right name for the location settings entity. It may not have a "_1" suffix.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "tdm_location_settings_1"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. (Volume is not included however. You'd just use the speaker property "s_volume" directly, but you'd need to restore it after the override is over if you don't want the change applying to all sounds.) You can change them dynamically in the same way as override. If you have multiple overrides, some with fading and some without, and want to revert to the default fading without looking it up, you can enter "-1" as the value of a property and it uses the default value.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-14T04:49:21Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, or for reading a book, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix mentioned above, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. If you open the console, it will report that the override ambient is playing. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $tdm_location_settings_1.setKey( "override", "[snd_name]"); to turn on an override sound and $[tls_1].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas. Also be sure to use the right name for the location settings entity. It may not have a "_1" suffix.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "tdm_location_settings_1"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. (Volume is not included however.) You can change them dynamically in the same way as override. If you have multiple overrides, some with fading and some without, and want to revert to the default fading without looking it up, you can enter "-1" as the value of a property and it uses the default value.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-14T04:47:51Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, or for reading a book, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix mentioned above, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. If you open the console, it will report that the override ambient is playing. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $tdm_location_settings_1.setKey( "override", "[snd_name]"); to turn on an override sound and $[tls_1].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas. Also be sure to use the right name for the location settings entity. It may not have a "_1" suffix.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "[tdm_location_settings1]"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. (Volume is not included however.) You can change them dynamically in the same way as override. If you have multiple overrides, some with fading and some without, and want to revert to the default fading without looking it up, you can enter "-1" as the value of a property and it uses the default value.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-10T08:00:20Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, or for reading a book, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix mentioned above, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. If you open the console, it will report that the override ambient is playing. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $[tdm_location_settings name].setKey( "override", "[snd_name]"); to turn on an override sound and $[tls_name].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "[tdm_location_settings1]"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. (Volume is not included however.) You can change them dynamically in the same way as override. If you have multiple overrides, some with fading and some without, and want to revert to the default fading without looking it up, you can enter "-1" as the value of a property and it uses the default value.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-10T06:33:37Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, or for reading a book, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. If you open the console, it will report that the override ambient is playing. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $[tdm_location_settings name].setKey( "override", "[snd_name]"); to turn on an override sound and $[tls_name].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "[tdm_location_settings1]"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. (Volume is not included however.) You can change them dynamically in the same way as override. If you have multiple overrides, some with fading and some without, and want to revert to the default fading without looking it up, you can enter "-1" as the value of a property and it uses the default value.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-10T06:26:21Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, or for reading a book, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $[tdm_location_settings name].setKey( "override", "[snd_name]"); to turn on an override sound and $[tls_name].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "[tdm_location_settings1]"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. (Volume is not included however.) You can change them dynamically in the same way as override. If you have multiple overrides, some with fading and some without, and want to revert to the default fading without looking it up, you can enter "-1" as the value of a property and it uses the default value.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-10T06:23:30Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, or for reading a book, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $[tdm_location_settings name].setKey( "override", "[snd_name]"); to turn on an override sound and $[tls_name].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "[tdm_location_settings1]"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. (Volume is not included however.) You can change them dynamically in the same way as override. If you have multiple overrides, some with fading and some withour, and want to just use the default fading, you can enter "-1" as the value of a property and it uses the default 4 second fade transition.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-10T06:09:34Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $[tdm_location_settings name].setKey( "override", "[snd_name]"); to turn on an override sound and $[tls_name].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "[tdm_location_settings1]"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. You can change them dynamically in the same way as override.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-10T06:07:30Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix, such as "snd_alert"), then the location system will fade out the location ambient and play the ambient sound you registered under that name as an override ambient. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $[tdm_location_settings name].setKey( "override", "[snd_name"]); to turn on an override sound and $[tls_name].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "[tdm_location_settings1]"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. You can change them dynamically in the same way as override.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-10T06:02:11Z

Demagogue: /* Sound Shaders */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers or if you use the override system.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix, such as "snd_alert"), then the location system will fade out the location ambient and play the override ambient. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $[tdm_location_settings name].setKey( "override", "[snd_name"]); to turn on an override sound and $[tls_name].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "[tdm_location_settings1]"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. You can change them dynamically in the same way as override.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-10T06:00:54Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" property for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix, such as "snd_alert"), then the location system will fade out the location ambient and play the override ambient. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override property to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" property dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a property on an entity is $[tdm_location_settings name].setKey( "override", "[snd_name"]); to turn on an override sound and $[tls_name].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "[tdm_location_settings1]"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new properties for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These properties are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the location settings entity and only apply to override ambients. You can change them dynamically in the same way as override.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-10T05:56:37Z

Demagogue: /* Sound Override */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" spawnarg for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix, such as "snd_alert"), then the location system will fade out the location ambient and play the override ambient. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override spawnarg to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" spawnarg dynamically, calling a script and triggering a target_setKeyVal entity in-game.

1. Script. The script function to change a spawnarg on an entity is $[tdm_location_settings name].setKey( "override", "[snd_name"]); to turn on an override sound and $[tls_name].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "tdm_location_settings1"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new spawnargs for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These spawnargs are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the lication settings entity and only apply to override ambients. You can change them dynamically in the same way as override.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Location Settings

2016-01-10T05:52:48Z

Demagogue: /* Sound Properties */

== Introduction ==

This article describes how to setup '''locations''' (also called "location zones" or "zones") in your level, and then use these to:

* fade to different ambient '''light levels''' for each zone
* fade between different ambient '''sounds''' in each zone
* run '''scripts''' automatically when the player enters or exits a zone

----

You need to use four types of entities in your map:

* a special global entity (e.g. add only one, the position does not matter): '''atdm:location_settings'''
* a special global light entity named '''ambient_world'''
* multiple '''info_location''' and '''info_locationseparation''' entities


:Note: Two alternative ways to get ambient sounds in your map are using speakers ([[Adding ambient Sounds to your Map]]), and using triggers ([[Ambient Sounds - Zone (using triggers)]]). Speakers are good if you only want your ambient to cover a definite radius and have a very simple setup. Triggers are basically obsoleted by the method in this tutorial. The only time you might still want to use a trigger-system is if you want a ambient sound to begin at a place where for some reason you can't create a portal to mark the zone boundary, but you can still have a trigger brush. There are some issues with a trigger system, too (f.i. their CPU and memory usage and more importantly they are not failsafe like locations are), that make the method in this tutorial superior.


== The atdm:location_settings entity ==

Create a '''atdm:location_settings''' entity in your blueroom (i.e., a room off to the side the player will never enter) or somewhere else in your map:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> atdm:location_settings'''

=== Default values ===

The location_settings entity takes a few ''default'' spawnargs related to the ambient light settings:

* [[Location Settings#"ambient_light_fade_time"|"ambient_light_fade_time"]]
* [[Location Settings#"ambient_light_fade_delay"|"ambient_light_fade_delay"]]

For their meaning and values, please refer to their sections.

=== update_period ===

The spawnarg '''update_period''' specifies the time in seconds between updates. A good value is 0.2, e.g. 5 times per second. That avoids to run the script too often, and still allows seamless transitions.

=== Sound Shaders ===

In the entity's spawnargs, put the names of all the ambient sounds you want to play in your map. (This pre-loads the sounds into the speaker so there isn't a pause when they start playing.) Put it in one of these property/value forms (without the quote marks):

'''"snd_streets" "city_night01_loop_z"'''

'''"snd_mansion" "sound/ambient/ambience/mansion_tense01a.ogg"'''

The left hand spawnarg should have a "snd_" prefix, and any name, but most useful is probably the name of the area it is for. You'll use this name again when you place the location markers.

The right hand value points to the actual sound file that will play. You can enter either the soundshader name, or the address where the sound file is (but see footnote). You can see the soundshader names of ambient-ready sounds in the sub-folder "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd". You can find the address of the sound files in "Darkmod/sound/ambient/ambience" (remember to start the address with "sound" in the spawnarg). You can also listen to the sounds at that location. They are are in .ogg format. But it's easier to just create a speaker (left-click>speaker) and it will give you a sound directory where can play sound files and find the names. No searching through sound folders outside of DR (thanks to Badcog for that tip).

:Note that it is very easy to add custom ambients with this system. Just create a folder in your .pk4 (a .zip file renamed to .pk4) and name the folder "sound", with another folder inside it named after your FM or an abbreviation. Put your custom sound inside that second folder. (E.g., I have a custom ambient named Frozen.ogg, and my FM's name is Patently Dangerous. So in my .pk4 was "sound/patent/frozen.ogg". Note that ambients must be in either .ogg or .wav format. Now in your speaker_zone_ambient, just put the sound's address in the spawnarg (but see footnote). In my case, I have "snd_warehouse" "sound/patent/frozen.ogg".

It is worth noting that one special "sound" is already loaded by default.

'''"snd_silence" "silence"'''

You can see it if you check "Show Inherited Properties". This is the sound you use to turn "off" the ambient sounds playing, so there is silence in the zone.

=== On Shader Names ===

One footnote on the sound shader names. The ''shader tdm_ambient_ambience_zoned.sndshd'' has a special command ("leadin") for its sounds that begins the ambient with a short pause. This is to pre-empt a possible *pop* of sound for loud ambients which can occur when the player's system slows down (and only occasionally, at that), so the player never hears the pop. (It's a quirk of how Doom3 does fade-ins; when you start a new sound, you have to rapidly fade it out first, like .001 seconds, then slowly fade back in. But if the system slows and the ambient starts loud, it might stretch that .001 to something audible.)
Edit:Baddcog- These seem to now have been appended with a _z if you look at sound names in speaker dialog.

If you alternatively use the address or the shader name from "Darkmod/sound/tdm_ambient_ambience.sndshd" (which lack the "leadin" property) it will otherwise work fine, but you won't be protected from that occasional little pop (at least until we find another fix). For ambients that start quietly or areas that won't slow the system down, it will probably never even be a problem and the player will never hear it, so using the address is fine, or using the tdm_ambient_ambience shader name if you don't want the tiny pause for whatever reason. But if you want to control it, use the tdm_ambient_ambience_zoned name, and for a custom sound, to pre-empt the pop you'll need to use a custom shader with the "leadin" line. Use the "Darkmod/sound/tdm_ambient_ambience_zoned.sndshd" as a template to do that, and name the custom shader file something like YourFMsName.sndshd, and put it in the "sound" folder in your .pk4.

=== Sound Properties ===

Regarding properties, the speaker (the '''atdm:location_settings''' entity is a speaker in disguise :) has by default the properties "omni", "global", and "looping" already turned on, so that all sounds played are heard everywhere, from no direction, and will loop. If you change these properties (e.g., for one ambient) the change will apply to all ambients on the speaker. So you probably don't want to turn these properties off.

Another spawnarg worth noting is "s_volume". Since the location_settings also acts as a speaker, this will work to change volume (0=full volume, -10=half volume, -60=silence), again globally on all the ambients playing on it. Unless you have a very good reason for doing so however (e.g., you want all your ambients much louder or quieter) you probably don't want to use the s_volume spawnarg. If you want to change the volume of a specific ambient, you can do so on the '''info_location''' entity with the "volume" spawnarg as described below (note some of the issues involved with volume changes there as well), not the location_settings entity (or directly in the sound's soundshader).

Your entity will look like this:

[[Image:Speaker4.jpg]]

=== Sound Override ===

From version 2.04, an "override" spawnarg for sounds has been added to the location settings entity. The purpose is to allow a mapper to easily override the location ambient to play their own sound, such as an ambient when a discovery is made, to build tension, action music when the player is seen, etc., and then return to the location sounds when it's done.

The default value for "override" is "0", meaning override is turned off, so the location ambients play as normal. Although it looks boolean, the data type is a string, so it takes any characters. If at any time in-game you dynamically change "override" to any non-zero value (I'll explain how below), it will override the location ambients to allow you to play your own sound as long as it is non-zero. To turn location ambient sounds back on, you change "override" back to "0".

If you change "override" to one of the pre-cached sound names (that is, a name with the "snd_" prefix, such as "snd_alert"), then the location system will fade out the location ambient and play the override ambient. The override ambient will continue to play until override is changed back to zero or to another override ambient. This means if you just want to play a one-shot ambient, you need to use a script with a wait function that waits the duration of the ambient then turns override off to restore the location ambient, otherwise it will loop.

If you change the override spawnarg to another value (not a sound name) such as "1", it will simply turn the system off, allowing the mapper to play a speaker in the silence if they prefer.

There are two basic ways to change the "override" spawnarg dynamically, calling a script and trigerring a target_setKeyVal entity in-game.

1. Script. The script function to change a spawnarg on an entity is $[tdm_location_settings name].setKey( "override", "[snd_name"]); to turn on an override sound and $[tls_name].setKey( "override", "0"); to turn the location ambients back on. Note because it's a string data type, you need to put zero in quote marks/inverted commas.

2. Target_setKeyVal. At the bottom of the entity list is target_setKeyVal (note it's not with other target entities). Create one of these entities and have it target the location settings entity (e.g., enter a property/key "target" "tdm_location_settings1"). Now add the property/key "keyval" "override;snd_name" to turn on the override sound. Note you separate the propery and key with a semicolon and no space. Now when you trigger that entity with a trigger brush, button, or anything else, it will change the propery and your override ambient will fade in. You can have another target_setkeyval entity with "keyval" "override;0" to turn override off and turn the location based ambients back on.

The tdm_location_settings entity has also got new spawnargs for fading behavior. Thus, the mapper can make the override ambient fade in as normal, or have it blast in with no fade-in if they want. These spawnargs are the same 'fading' type spawnargs as are on the info_location settings described below, and work in the same way, except they are on the lication settings entity and only apply to override ambients. You can change them dynamically in the same way as override.

You are finished with the ambient sound part now.

== The Ambient Light ==

You need to create an ambient light in your level. This will cover the entire level, and provide a minimum default light for when there is no other light covering a surface:

# '''{{RMB}} -> Create light'''
# Move the light's origin to the center of your map, and drag it's size so that it covers your entire map, and then some more. Remember to increase the size of that light when you build more area into your map!
# Open the light inspector (default shortcut {{key|L}}) and set the light texture to '''lights/ambientlightnfo'''
# Set the color of the light to a reasonable default, f.i. "8 8 8" This value will be used when a zone has no other ambient light settings
# Open the entity inspector (default shortcut {{key|N}}) and set the name of the light to '''ambient_world'''

The last step is important!

You are done now with the global ambient light.

== The Location Entities ==

Now you need to set up the location system so the game knows where the zones are, and their boundaries where changes will happen. A location is basically any area that's closed in by brushes and marked portals and contains an info_location entity. Unlike a vis-portaled area (which is one area between [[vis_portals]], a.k.a. a "leaf"), a zone can cover more than one portaled area ("leaves").

As an aside, locations are also used for setting the EAX properties in the area (e.g., the echo-y-ness of a big hall or cave, or the dullness of a small carpeted room). So you have a good reason to have them even in addition to handling ambient sounds and lights.

=== info_locationseparator ===

As I suggested above, you have to mark all the portals leading in and out of a zone by hand. You do this with an entity called a '''info_locationseparator'''. Create one so it touches the portal you want as a boundary.

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_locationseparator'''

If you don't touch a portal with this entity, than it will not register in the game as the boundary to a new zone, and the zone will continue into the area on the other side of the portal. This happens even if you have a second info_location (described below) on the other side (the game will just pick one and use that for the whole zone). This can be a good thing because, say you have a mansion with 30 portals inside. You can cover the whole area inside it by just marking the 2 or 3 portals leading into the mansion area through the doors and open windows, and everything inside that marked area will be counted as one location (just don't miss marking an exit, or have an un-portaled gap to the outside between brushes, or the location will leak outside. It has to be hermetically sealed).

I have read discussion that a door touching a portal marks it as a location boundary, but in my experiments the door did not create a new location and I still had to use a info_locationseparator over the portal to register it as a boundary.

=== info_location ===

Now, inside the zone you want to have, create an '''info_location''' entity:

'''{{RMB}} -> Create entity -> Darkmod -> Info -> info_location'''

Anywhere in the space of the zone is fine. Name it the name of the zone you want (to make it easy to find when you push {{key|J}}).

== Settings per location/zone ==

On each info_location, you can set multiple spawnargs that adjust the light or sound for that location, as well
as run scripts. We cover them next:

=== Ambient sound ===

Now create a spawnarg property of "ambient" with the value being the speaker-name of the sound you used in the location_settings entity above (NOT the soundshader name or file name). For example,

'''"ambient" "snd_streets"'''

This will send a command to the location_settings (in its speaker capacity) to play the ambient it has registered under "snd_streets" that you entered. When you enter a new zone, in turn, the new info_location sends a command to the speaker to turn off that ambient and start a new one.

If you wanted to have no ambient playing in the zone (and turn off any ambient started from another zone), you would use "snd_silence" as the value to command the speaker to turn off. Also, if you have an info_location with no "ambient" value at all, it will also turn off the ambient (in the present version of this system). That means if you make a new location but want the same ambient playing in it as the location next to it, you still need to add the ambient name for the already-playing ambient for it to continue playing into the new zone; otherwise it will turn off.

==== Examples ====

Here are two info_locations on two sides of a portal, with an info_locationseparator touching the portal (more like piercing it), and with each info_location containing the name of the ambient that will play in its respective zone.

[[Image:Snd_streets.jpg]]

[[Image:Snd_silence.jpg‎]]

That's basically it. The ambients will now turn on when you enter a zone and turn off when you enter a new zone, turning on the new ambient in that new zone (unless it's the same ambient, then it just keeps playing, useful e.g., if you want 2 different EAX but 1 ambient playing). If you open up the console, you should see a message saying that a new ambient is now playing in your current location, naming the ambient and location.

=== Sound Fading ===

Finally, there are a few other spawnargs on the info_locations that you usually don't have to worry about (with the possible exception of "volume"), but you can use them if you like, so I will mention them. They concern the properties of the ambient fading. Check the "Show Inhereted Properties" to see their default values. Entering a new value will over-write the default value, but only for that one object.

[[Image:Info_loc.jpg‎]]

==== fiduration ====

"Fade in duration". This is the length of time in seconds it takes for the in-coming ambient (the one for this zone) to completely fade-in. The default value is 4 seconds. You can, e.g., make the fade last much longer with a larger value.

If you don't want your ambient to fade in at all, but start immediately at full volume, change this value to ".001" (NOT zero).

==== foduration ====

"Fade out duration". This is the length of time in seconds it takes for the out-going ambient (the one from the zone you're leaving) to completely fade-out. Again, if you want it to cut right off without fading, use a value of ".001".

==== fidelay ====

"Fade in Delay". You can delay the beginning of the in-coming ambient's fade-in after you enter the new area. You might want to do this, for example, if you want the out-going ambient to completely fade out before you begin fading in the new ambient. So you would set fidelay to the same time as the foduration. By default it is set to .001 so that there is no delay and the fade in starts immediately. If the out-going fade-out also starts immediately (which happens by default), then they blend together in a nice transition fade.

==== fodelay ====

"Fade out Delay". Similarly you can delay the beginning of the out-going ambient's fade out. You might want to do this if you wanted the in-coming ambient to completely fade in before you started the fade out of the old ambient. Then you would set it to fiduration. Like fidelay, it is set to .001 so there is no delay and the fade out starts immediately.

==== fovolume ====

"Fade out volume". This sets the volume to which the out-going ambient fades to. -60 turns it off, which is the default (0 means no decrease in volume at all). If you go any higher than -60, than it will leave the old ambient still playing at a lower volume under the new ambient (at least until you enter a 3rd new zone). Not sure why you'd ever want to do that, so you probably don't want to change it.

==== volume ====

This allows the mapper to override the volume of the ambient sound once it has fully faded in, and uses the same decibel scale as the '''s_volume''' speaker parameter. Note, though, that it uses the spanwarg "volume" instead. I found a decibel-loudness calculator here: http://www.sengpielaudio.com/calculator-levelchange.htm that lets you compute the decibel number for relative loudness. According to it, "0" is the native volume of the sound (the default), "-60" is silence, "-4" is 3/4 (.75) of the volume, "-10" is half (.5) the volume, "-17" is 0.3 of the volume, and it goes quickly down from there. "10" is double, but be warned there may be problems with positive numbers (e.g., volume clipping) and you should keep it not far above 0 if at all. See [[Setting Up Speakers#volume/ s_volume|"Volume / S_Volume"]] & [[Volume Issues]] for more detailed discussion of the volume parameter.

'''Do not override ambient volumes unless strictly necessary'''. Maps with wildly different ambient volume settings result in a poor experience for players, and limit the ability of the Dark Mod team to respond to volume-related issues by changing default volumes in sound shader declarations.

These last two ('''foduration_2foip''' and '''fiduration_2foip''') are pretty obscure situations, so you probably don't need to ever mess with them unless you want to completely get rid of ambient fades (then you can set them to .001 like the other 'fade duration' properties).

==== foduration_2foip ====

"Fade-out duration during a '2 Fade-outs in progress' situation". This provides a shorter fade-out duration (in seconds) for when the player quickly runs into a 3rd location, such that the 1st and 2nd ambients from areas the player just left are still fading out (hence the 2 fade-outs). But the quickend-fade-out only applies to the 1st ambient fading out. (i.e., not of the ambient you just left, but the one you left just before that -- unless you're backtracking, then it just fades the prev-prev ambient back in). Fading out that prev-prev ambient more quickly in turn quickens the time the new fade-in can start (because you can't have 3 sounds on at the same time on the zone speaker, only 2). So it in effect reduces the gap of quiet that happens before the newest ambient fully fades-in by enabling it to start its fade-in faster. The default is 1 second.

==== fiduration_2foip ====

"Fade-in duration during a '2 Fade-outs in progress' situation". Like its counterpart, this sets a shorter duration of a fade-in of a new ambient (in seconds) when you run into a 3rd location, while the ambients from the 1st and 2nd locations are fading out. Again, because so many ambients are fading out, it can leave a gap of silence for a bit until the new 3rd ambient fades in. So setting a shorter duration than usual for the newest ambient to fully fade in helps shorten the quiet space. The default is 2 seconds (as opposed to a normal default fade-in duration of 4 seconds).

==== Example of Location with No Fading Transition ====

As mentioned above, if you wanted a set-up that turned off all fades so that the out-going ambient shut directly off and the in-coming ambient turns directly on, you'd change all the duration properties to .001, like the following image. (Note that this modifies the transition only for entering this one location. All the other info_locations maintain their default values unless you also change them by hand.)

[[image: Fade_duration.jpg‎]]

=== Ambient light settings ===

These spawnargs can be set on '''atdm:info_location''' entities and apply to the current zone then:

==== "ambient_light" ====

This spawnarg specifies the ambient light color for this zone. Setting it f.i. to "0.10 0.02 0.02" would fade the ambient light to a slightly reddish color. This can be useful for covering a lava cave. Other examples are slightly blue light for moonlit outsides, greenish cast for caves or underwater areas etc.

If you do not set this on an info_location entity, the default value of the global "ambient_world" entity will be used.

'''Notes:'''

:*You need to set the color values as fractions between 0 and 1, e.g. '''"0.08 0.08 0.02"''' and '''NOT''' as integers like so <s>"8 8 2"</s>, or it will not work.

:*If the color change between two zones is too big, the fading and change can become obvious to the player and spoil the subtlety. This can happen for instance if you zoom from a bluish-lit outside directly to a reddish-glowing cave inside. To help the transition, consider adding an intermidiate zone with a light color that is either in between the two, or a more neutral grey. Making it not possible to look from one zone to the other also helps, this way they player can't see that f.i. the outside ground suddenly also glows reddish when looking back from the cave entrance to the outside.

==== "ambient_light_fade_time" ====

This specifies the time in seconds it will take to fade from the current ambient light color to the one specified for this location. A slower fade means more gradual light changes, so they don't become too obvious to the player. Use at least 3, better 5 or 7 seconds.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_fade_delay" ====

This specifies the time in seconds the fading will be delayed when the player changes location.

Useful to prevent fades toggling back and forth when the player stands in a doorway and goes a nudge forward/backwards. A good value is at least 1 second.

If set to -1, the default time specified at the '''atdm:location_settings''' entity will be used.

==== "ambient_light_dynamic" ====

'''This is a factor''', all lights in the current area will be summed together and scaled by this value.

If set to a value other than "0 0 0", the lights in the current zone will be all summed together and then
added to the current base ambient light. This happens with the frequency of '''update_period'''.

The basic effect is that a roaring fire also slightly makes the walls flicker, and extinguishing all lights in a room would decrease the ambient light slightly.

The factor should be set up so that for large and dark rooms (e.g. caves) the dynamic part is small, while for small, bright rooms (white walls) the dynamic part is bigger. Examples are: "0.05 0.05 0.05" and "0.1 0.1 0.1".

Note that setting the dynamic factor to high can result in the player being busted by lights that are turned on in the room even when the player is in the shadow.

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dynamic_cap" ====

Used to cap the dynamic ambient light part. If set to 0, will be ignored, so to have a very very small
cap, set to "0.01", e.g. if you want only the red part to be dynamic, set it f.i. "0.15 0.01 0.01".

See also the article about [[Dynamic ambient light]].

==== "ambient_light_falloff" ====

Possible values are:

* -1 on info_location: use the value from the atdm:location_settings entity
* 0 - no dynamic falloff
* 0.5 - small, based on square root of distance
* 1 - medium, linear dynamic falloff (should be used as it looks best)
* 2 - high, square of distance based falloff

See also the article about [[Dynamic ambient light]].

==== "ambient_light_dist_scale" ====

A factor to scale the distance before applying a dynamic light falloff. Only used then '''ambient_light_dynamic_falloff''' is not 0. Good valuesa are around 1.0.

See also the article about [[Dynamic ambient light]].

=== Script calls ===

The next four spawnargs all specify scripts to call when the player enters or exits a zone. Note that the very first zone is also "entered" by the player when the map starts. That means "call_once_on_entry" for the start zone should be called at start-time.

==== "call_once_on_exit" ====

Called only once when the zone is left by the player.

==== "call_once_on_entry" ====

Called only once when the zone is entered by the player.

==== "call_on_exit" ====

Always called when the player leaves that zone.

==== "call_on_entry" ====

Always called when the player enters that zone.

==== Example scripts ====

Here is an example script that spawns an object where the '''info_location''' entity is for the zone the player just left. You can call this script by setting:

'''"call_once_on_exit" "spawn_pear"'''

on your info_location entity.

<pre>
void spawn_pear( entity old_zone )
{
// Get the name of the location that the player just left:
string location_name = old_zone.getName();
// and display it on the console for debugging
sys.print ("Spawning pear after leaving " + location_name + "\n");
// spawn the pear entity
entity pear = sys.spawn("atdm:moveable_food_pear");

// and now get the position of the old location entity:
vector origin = old_zone.getOrigin();
// finally move the pear to the point of the info_location
pear.setOrigin( origin );
// so once the player exits this location, ONE pear will spawn and fall down
}
</pre>

==== Example script to turn entities on/off when player enters a location ====
The basic problem with normal TDM entity work is the difficulty of turning something deliberately and reliably on or off. You never turn something on or off, but instead you send toggles to the entities. Let's say you have a omni sound (a sound which is heard everywhere) which you need to shut off when the player goes to a certain location. Trigger_multiples trigger targets when the player stands on their volume, which may result in a completely wrong situation depending how long the player stands on the trigger.

Location entity scripting can be of great help in here. This kind of scripting can generally solve any kind of problems where the mapper want something to be switched specifically on and off when the player moves to a specific location. Here is an example, which was used to switch off a global thunder sound when the player moves to a location where the rumbling cannot be heard.

Set up location setting as described above. Put a location separator on the visportal you want to be the point which switches your target on/off. Give the info_location-entity spawnargs
*call_on_entry yourscript
*call_on_exit yourscript

Then go and create in your /maps folder a file yourmapname.script. Put in the following data there:

void yourscript(entity old_zone)
{
sys.println("script yourscript running..");
sys.trigger( $entity_name );
}
void main()
{
}

*yourscript is the name of your script you call.
*sys.println is a debug feature which gives the text in console when the script is triggered. You can leave it for testing and remove it before releasing your map.
*sys.trigger ($entity_name) replace the entity_name with the entity which you want to be triggered.

Now your system works like this:
*When the player is outside the location everything is normal. Ie sound off, light off, etc.
*When the player enters the location, entity_name gets triggered once. Ie sound on, light on, etc.
*When the player leaves the location, entity_name gets triggered again. Ie sound off, light off, etc.

== See also ==

* [[Adding ambient Sounds to your Map]]
* [[Dynamic ambient light]].
* [[Ambient Sounds - Zone (using triggers)]]
* [[Sound File Formats]]

{{tutorial-sound}}
{{editing}}
{{tutorial-scripting}}
[[Category:Ambient Light]]

Custom Settings for Players

2015-12-02T16:09:37Z

Demagogue: /* Making Hotkeys */

This page lists various settings that users can modify to make their game experience more to their liking.

There are two ways to adjust these settings. You can find and modify them inside your doomconfig.cfg file, or you can pull down the console ({{key|CTRL}} + {{key|ALT}} + {{key|~}}, always the key under the {{key|ESC}} key) while the game is running and type the value directly into the console.

== Toggles ==

* '''seta in_toggleCrouch''' If set to '''"1"''', causes the crouch button to act as a toggle. Defaults to "0"
* '''seta in_toggleRun''' If set to '''"1"''', causes the run button to act as a toggle. Defaults to "0"
* '''seta in_alwaysRun''' If set to '''"1"''', causes the player to always run. (probably not useful in a stealth game). Defaults to "0"
* '''seta pm_lean_toggle''' If set to '''"1"''' causes leaning to work as a toggle. Defaults to "0"

== Making Hotkeys ==

To set hotkeys for inventory items, add the following line(s) to your doomconfig.cfg file, or type them into the console.

*'''bind "[button]" "inventory_hotkey [item]"'''

For example, '''bind "F1" "inventory_hotkey Flashbomb"''' will automatically select your flashbomb in inventory when you press {{key|F1}}.

Note that you can use the '''Controls Menu''' to set a hotkey for the compass, lantern, (under '''Weapons''') and maps (under '''Other''').

The other inventory objects you may wish to create a hotkey for are:

*"Spyglass"
*"Breath Potion"
*"Health Potion"

You can bind the bow zoom to a hot key with:
bind [button] "toggle g_fov 90 45"

== Other ==

* '''tdm_frob_weapon_selects_weapon''' If set to '''"1"''' weapons are automatically selected when the respective arrows are frobbed.
* '''tdm_weapon_next_on_empty''' If set to '''"1"''' weapons will automatically cycle to the next weapon when you run out (in other words, after you fire your last water arrow you will immediately equip your fire arrows--generally not a good idea.

*'''seta tdm_door_auto_open_on_unlock ''' Default setting makes doors swing open automatically when they are unlocked. Set to '''"0"''' to make doors stay closed until you frob them.

*'''Disable Bow Zoom''' In script/tdm_weapon_arrow.script there is a line "#define ARROW_ZOOMAMOUNT 60". Changing it to "#define ARROW_ZOOMAMOUNT 90" will disable the bow zoom. If you are using a different fov as 90°, you'll have to set it to the specific number. To apply this change, extract the file from the pk4 (can be opened like a zip file, as they are zips) and put it in a script folder in your darkmod installation (you have to create said folder). Alter the file there. This file will than override the one in the pk4 (literally).

See also [[Console Useful Controls]]

{{general}}
[[Category:Gameplay]]

Custom Settings for Players

2015-11-27T01:36:25Z

Demagogue: /* Other */

This page lists various settings that users can modify to make their game experience more to their liking.

There are two ways to adjust these settings. You can find and modify them inside your doomconfig.cfg file, or you can pull down the console ({{key|CTRL}} + {{key|ALT}} + {{key|~}}, always the key under the {{key|ESC}} key) while the game is running and type the value directly into the console.

== Toggles ==

* '''seta in_toggleCrouch''' If set to '''"1"''', causes the crouch button to act as a toggle. Defaults to "0"
* '''seta in_toggleRun''' If set to '''"1"''', causes the run button to act as a toggle. Defaults to "0"
* '''seta in_alwaysRun''' If set to '''"1"''', causes the player to always run. (probably not useful in a stealth game). Defaults to "0"
* '''seta pm_lean_toggle''' If set to '''"1"''' causes leaning to work as a toggle. Defaults to "0"

== Making Hotkeys ==

To set hotkeys for inventory items, add the following line(s) to your doomconfig.cfg file, or type them into the console.

*'''bind "[button]" "inventory_hotkey [item]"'''

For example, '''bind "F1" "inventory_hotkey Flashbomb"''' will automatically select your flashbomb in inventory when you press {{key|F1}}.

Note that you can use the '''Controls Menu''' to set a hotkey for the compass, lantern, (under '''Weapons''') and maps (under '''Other''').

The other inventory objects you may wish to create a hotkey for are:

*"Spyglass"
*"Breath Potion"
*"Health Potion"

== Other ==

* '''tdm_frob_weapon_selects_weapon''' If set to '''"1"''' weapons are automatically selected when the respective arrows are frobbed.
* '''tdm_weapon_next_on_empty''' If set to '''"1"''' weapons will automatically cycle to the next weapon when you run out (in other words, after you fire your last water arrow you will immediately equip your fire arrows--generally not a good idea.

*'''seta tdm_door_auto_open_on_unlock ''' Default setting makes doors swing open automatically when they are unlocked. Set to '''"0"''' to make doors stay closed until you frob them.

*'''Disable Bow Zoom''' In script/tdm_weapon_arrow.script there is a line "#define ARROW_ZOOMAMOUNT 60". Changing it to "#define ARROW_ZOOMAMOUNT 90" will disable the bow zoom. If you are using a different fov as 90°, you'll have to set it to the specific number. To apply this change, extract the file from the pk4 (can be opened like a zip file, as they are zips) and put it in a script folder in your darkmod installation (you have to create said folder). Alter the file there. This file will than override the one in the pk4 (literally).

See also [[Console Useful Controls]]

{{general}}
[[Category:Gameplay]]

FAQ

2015-02-10T08:10:18Z

Demagogue: /* Updater (tdm_update.exe) crashes at some point during the update */

{{important|headline=Important|text=This FAQ relates to the full TDM release version only. For players of the pre-release demos such as '''[[Thief's Den]]''' and '''[[Saint_Lucia|Tears of Saint Lucia]]''' please refer to the '''[[FAQ (Demo Releases)|Demo FAQ]]'''.'''}}

== What do I need to play The Dark Mod? ==

With the release of TDM 2.0, you no longer need Doom 3 installed. The Dark Mod is completely standalone (and free!). You need only follow the installation instructions on the website to start playing the game.

== Supported Operating Systems ==

=== Which Windows versions can I use? ===

The following versions of windows have been tested and are known to work : Windows 2000, Windows XP, Windows Vista, Windows 7, Windows 8, Windows Server 2008, Windows Server 2003 in both 32bit and 64bit flavours.

==== Windows 8.1 Preview ====

Thus far, on Intel HD graphics, TDM will not start unless it is started in Windows 7 compatibility mode:

Right click "TheDarkMod.exe" choose "Properties", click the "Compatibility" tab and select Windows 7 from the dropdown
list.

This may not be representative of other graphic hardware and may be due to early Windows 8.1 driver support.

==== PAE Enabled ====

One user with Windows XP Pro SP3 and an AMD Phenom processor reported problems starting Doom 3 due to having PAE enabled.

[http://modetwo.net/darkmod/index.php?/topic/12471-error-doom-3/ Thread]

=== Does it run in Linux? ===
Yes, Linux is supported.

=== Does it run in 64 Bit Linux? ===
Yes, Linux 64 bit is supported. In addition to the steps above, you need 32 bit compatibility libraries, since Doom3 is 32 bit only:
* On '''SuSE''', they should be included.
* On Ubuntu/Kubuntu, install the package '''ia32'''.

For TDM after 1.0, this step should be '''no''' longer neccessary:

* Since you cannot install 32 bit libraries on a 64 bit system with the normal package manager, you should use [http://ubuntuforums.org/showthread.php?t=474790 getlibs] to install '''libmng''' and the boost filesystem lib:
:<code>getlibs libmng.so.1</code>
:<code>getlibs -l libboost-filesystem1.34.1</code>

=== What about Gentoo? ===
Yes. It's not "officially" supported (the team doesn't test it specifically), however several users have reported success running TDM under Gentoo.

=== What about Ubuntu 8.10? ===
Yes. As of this writing you will need to install the '''libboost-filesystem''' package.

=== GLIBCXX_3.4.9 errors ===

If you receive an error about <tt>GLIBCXX_3.4.9</tt>, delete or rename the files <code>/usr/local/games/doom3/libstdc++.so.6</code> and <code>/usr/local/games/doom3/libgcc_s.so.1.</code>

If this doesn't resolve the error and you have an old version of GCC, then you may have to upgrade. It has been [http://modetwo.net/darkmod/index.php?/topic/9982-the-dark-mod-doom3-in-linux/ confirmed] that, at least under Gentoo, GCC 4.1 does not work with TDM but GCC 4.3 and GCC 4.4 are compatible.

=== Does it run on Mac OS X?===
TDM 1.08 is supported, but 2.0 is not. See [[Installation]].

== Graphics ==

=== Does TDM support widescreen resolutions? ===

Yes. Choose "16:9" or "16:10" in the in-game ''Settings'' menu, and select the appropriate resolution. Note that you need to restart the game to have the new setting in effect.

If the native resolution of your wide screen monitor is not listed, you can enter it into '''DoomConfig.cfg''' by changing the following entries like so:

set r_mode "-1"
set r_customwidth "1280"
set r_customheight "800"
seta r_aspectratio "2" // means 16:10, "1" is 16:9, other ratios are not yet supporred

{{infobox|If you get performance problems, please consider using a lower resolution and taking a look at [[Performance Tweaks]].}}

==== What about TV resolutions like 1360x768? ====

If you have a wide-screen TV which uses any non-standard resolution, like 1360x768 (instead of 1366x768), then please use the following:

seta r_customWidth "1360"
seta r_customHeight "768"
seta r_mode "-1"
seta r_aspectratio 2
seta g_fov "100" // or any other suitable value

Alternatively, see the manual of your TV on the possibility to switch it to a "1:1" pixel mapping, or "monitor mode" or "computer mode".

Here is some background information: http://hd.engadget.com/2006/04/21/whats-the-deal-with-1366-x-768/

{{infobox|If you get performance problems, please consider using a lower resolution and taking a look at [[Performance Tweaks]].}}

== Troubleshooting ==

It is hard to answer questions on why something fails, because wildly different systems cause wildly different symptoms. If the following section does not help you, please ask at our [http://www.modetwo.net/darkmod forums].

For any solutions below that refer to "disabling Catalyst AI", if you discover you can not use ATI's tools to do so, alternate methods are discussed in [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] below.

=== Can't load saved games -- TDM gives error about "can't load .script" file ===

Make sure your folder is called "darkmod". If it isn't, rename it. That should make the problem go away. I've heard reports that having spaces in the names of any folders in the path can cause problems, but haven't confirmed it. Something to try if it still happens and your folder is already called "darkmod".

=== Updater (tdm_update.exe) closes almost as soon as it's started ===

See the [[Tdm_update#Updater_closes_almost_as_soon_as_it.27s_started|main article on tdm_update]].

=== Updater (tdm_update.exe) crashes at some point during the update ===

The Windows update will crash at the "Applying Update" stage if the Darkmod folder is set to "read only". You fix it by right clicking on the folder, going to folder properties, and unchecking the box that says "read only" under folder attributes.

=== Windows 2000: freeaddrinfo cannot be found in WS2_32.DLL ===
Please refer to the main article [[TDM in Windows 2000]] to work around this problem.

===FM won't install manually===

If you are running Dark Mod under Linux and have edited the file darkmod/currentfm.txt this might prevent the FM from installing. This may be fixed in an update but apparently editing using notepad under Wine works OK.

=== FMs downloaded but don't show in menu list===

You have downloaded some FMs but they don't show on Dark Mod's New Missions list. Possible causes:

* You must not extract the pk4s or zip files but put them into the darkmod/fms folder (or alternatively you can create the FM folder in there eg, darkmod/fms/chalice for chalice.pk4 or chalice.zip.
* Early versions of Dark Mod cannot handle zip suffixes. Solution: rename to .pk4 or run tdm_update to get the latest version of Dark Mod.

=== FM downloaded but won't play ===

If you have downloaded an FM you might see it in the New Missions List but can't get it to play. These are almost always an install problem. These are some of the causes and cures:

FMs (fan missions) are archives and in early versions of Dark Mod MUST be suffixed .pk4 not zip. Apparently Internet Explorer 8 may change it from pk4 to zip during download without telling you. You need to rename it back if running an early version of Dark Mod else run tdm_update to update and then zip files are OK.

You do NOT need to extract the pk4 archives to install or play. Just download into or move the pk4 into the darkmod\fms folder. Optionally you can create a folder of the same name as the map and put it in there, eg, darkmod\fms\chalice but there is no need because Dark Mod will create that automatically. Just make sure your pk4 goes, unopened, into the fms folder, then run TheDarkMod.exe

If you have done the above but see for example, a blank objectives screen and no briefing then it is still almost certainly an install error. I recommend you do a clean sweep if in doubt:
* Exit Dark Mod
* Delete darkmod\currentfm.txt (this just uninstalls any FM)
* Move the pk4 into the darkmod\fms folder if it is not already there.
* Delete the darkmod\fms\FMname folder if any, eg, darkmod\fms\chalice. Don't worry if there isn't one; it will be created automatically later.

So all that is left is the pk4 in the fms folder. Now run TheDarkMod.exe. The FM should be in the list in the New Missions menu. Re-install it and you should now be able to play it.

=== The game hangs at Dark Mod screen/ locks up while turning on vsynch ===
Catalyst Control Center above 10.8 for ATI cards has a performance slider for V-Synch. Setting that slider to Quality (Always On)
fixes this issue. If set lower than quality and it is set to on in game it will freeze.
(tested specifically in CC 10-11)

=== The game crashes on load ===
Make sure that:
* Your system meets at least the minimum system specs.
* You have enough free main memory. Try closing a few running programs like Outlook, Anti-Virus or torrent clients.
* Nvidia "Threaded Optimizations" are causing Doom 3 Mod stability issues (see: [[#Disable Nvidia "Threaded Optimizations"|Disable Nvidia "Threaded Optimizations"]] )

If that doesn't fix it, you probably receive an error message referencing an "Unknown event" at startup, like the screenshot below illustrates.

[[Image:ErrorSetEntityRelation.jpg]]

Here are a couple of known problems and their solutions:
<ul>
<li>Sometimes, the procedure fails due to '''spaces in the installation path'''. Try extracting the gamex86.dll manually using Winzip or similar or install Doom 3 in a different directory.</li>
<li>You have a '''firewall''' installed that prevents the copy procedure, because since version 1.03, TDM has a built-in mission downloader. This misbehavior has been reported for the '''COMODO Firewall'''.</li>
</ul>
<li>It is also possible that an '''old version of gamex86.dll''' (or gamex86.so) is lying around in your Doom 3 folder. Delete it and try again.</li>
</ul>

=== Textures are missing, screen mostly black ===

[[Image:Tdm missing textures.jpg|right|240px|Black textures]]

Look into your '''darkmod.cfg''' inside your <tt>darkmod</tt> folder and check that the following settings are like shown below:

<pre style="max-width:35em">
seta image_usePrecompressedTextures "1"
seta image_useNormalCompression "2"
seta image_useAllFormats "1"
seta image_useCompression "0"
seta image_preload "1"
</pre>

=== Textures are missing, shadows are pitch black ===

Try disabling the AGP surface accelerator in DXDIAG.

=== Graphic Corruption ===

One report we had was for a Radeon ATI HD 4650, catalyst 10.9. This screen corruption as I understand it was heavy pixelation even on the menus. Closing down Xfire fixed it. "I fiddled with the xfire Doom 3 configuration through the xfire_games.ini, and determined it has to do with InGameFlags portion. For some reason the settings in that were interfering with doom 3, and after I removed some things from there, I was still able to run xfire, and doom 3 was still able to look proper."

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== The briefing is very fuzzy ===

Look into your '''DoomConfig.cfg''' inside your <tt>darkmod</tt> folder and check that the following settings are like shown below:

seta image_roundDown "1"
seta image_forceDownSize "0"
seta image_downSize "0"

=== The sky is corrupted ===

You either see black sky, or fragments of other textures. This seems only to happen on Geforce 6800 cards.

There are two fixes for this:

As a quick fix you can rename the following folder:

env/skyboxes/skybox_darkland_ne

to a different name. That will result in black sky.

Alternatively, edit the file <tt>materials/tdm_sky.mtr</tt> with '''Wordpad''' or a different editor and
find the sky material named '''textures/darkmod/nature/skybox/skybox_darkland_NE''':

<pre>
//Author: Dram
//skybox_ocean with ocean replaced with dark land
//Moon moved to north east by Fidcal
textures/darkmod/nature/skybox/skybox_darkland_NE
{
qer_editorimage env/skyboxes/skybox_ocean/ocean_ed
noFragment
noshadows
noimpact
nooverlays
forceOpaque
{
forceHighQuality
blend add
cameraCubeMap env/skyboxes/skybox_darkland_ne/darkland_NE
texgen skybox
texgen wobblesky .0 .0 .0
}
}
</pre>

In this declaration, comment out the line that reads '''forceHighQuality''' by adding <tt>//</tt> in front of it:

// forceHighQuality

That should fix the sky and make it render correctly.

=== The Sky rotates ===

This problem only affects FMs with a dynamic sky (eg, moving clouds etc.).

If you see the sky spinning it may be an ATI graphics card problem. One report says this was cured by turning off Catalyst AI. Also gives better loading times and cures [[#HDR-Lite Post-Processing problems|HDR-Lite Post-Processing Problems]].

If that doesn't fix it then try this. Note that it replaces dynamic sky with a static clear one so it might look odd in a stormy FM for example, but better than a spinning sky:

<pre>

* Create a new folder in your darkmod folder called materials.
* Within it create a plain text file named no_skybox.mtr.
* Paste in the following:

textures/smf/portal_sky
{
qer_editorimage env/skyboxes/skybox_ocean/ocean_ed
noFragment

noimpact
nooverlays
forceOpaque
noShadows
{
forceHighQuality
blend add
cameraCubeMap env/skyboxes/skybox_darkland_ne/darkland_NE
texgen skybox
texgen wobblesky .0 .0 .0
}
}

</pre>

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== HDR-Lite Post-Processing problems ===

Some owners of ATI graphics cards reported various artifacts when HDR-Lite Post-Processing was enabled. Among these artifacts are a distorted or upside-down screen and spinning sky. These can usually be fixed by disabling Catalyst AI, which also gives better loading times.

To turn off Catalyst AI, open your Catalyst control panel, go to 'graphics' at the top left, select '3d' from the dropdown list and on the new menu below, select 'AI'. Now select the 'Disable Catalyst A.I.' checkbox.

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

It has also been suspected that HDR-Lite Post-Processing may lead to [[#Underwater performance poor|poor performance underwater]], see next point:

===Underwater performance poor===

Some people suffer from very low framerates underwater with HDR-Lite Post-Processing enabled. Currently, the only known fix to this problem is to set '''g_doubleVision''' to 0 in the console. This however disables the doubleVision effect completely, so that there is no underwater-blur any more. The murkiness still remains though.

===Upside-down screen===

If you get an upside-down screen, you can either turn off Catalyst AI if you have an ATI card or try turning off HDR-Lite Post-Processing in the advanced video options.

To turn off Catalyst AI, open your Catalyst control panel, go to 'graphics' at the top left, select '3d' from the dropdown list and on the new menu below, select 'AI'. Now select the 'Disable Catalyst A.I.' checkbox.

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== The game is '''very''' slow! ===

If you get less than 10 FPS, or the game even stutters, please try this:

Look into your '''DoomConfig.cfg''' inside your <tt>darkmod</tt> folder and check that the
following settings are like shown below:

<pre style="max-width:35em">
seta image_usePrecompressedTextures "1"
seta image_useNormalCompression "2"
seta image_useAllFormats "1"
seta image_useCompression "1"
seta image_preload "1"
</pre>

If that doesn't help, your system might run out of memory. Either upgrade to more than 1 Gbyte memory,
or try to close other applications before playing.

Please see also the article about [[Performance Tweaks]] to improve the performance.

=== Slow loading times ===

If you find an FM is very slow to load it may be an ATI graphics card problem. One report says this was cured by turning off Catalyst AI. Also cures [[#HDR-Lite Post-Processing problems|HDR-Lite Post-Processing Problems]].

Changing the following settings to 0 will also reduce loading time, but be warned: if you have a lower-end system, poor graphics card, or low ram, you will likely notice a performance hit ingame since you will now be using uncompressed textures.
<pre style="max-width:35em">
seta image_useNormalCompression "0"
seta image_useCompression "0"
</pre>

===Game freezes for several seconds when opening doors===
The following problems :

A) "game freezes and loads some data from hard drive while opening doors"
B) "while loading mission you are returned to the menu and need to restart loading"

are often resolved by disabling EAX 4.0 HD in the Audio Settings menu.

===Game exits to menu after mission load, with renderpipe error in console===

* {{Red|Version 1.06 does not use named pipes. This is a depreciated issue.}}

'''Symptoms:''' Missions are installed properly and will load, but after they reach 100% you are returned to the main menu or objectives screen. If you open the console (Ctrl-Alt-~ on US keyboards), you see one/both of these errors:

ERROR: Failed to open \\.\pipe\dm_renderpipe

or

ERROR: idRenderSystemLocal::uncrop currentcrop <1

'''Solution:''' Some firewalls, notably ''Sunbelt Firewall'' (aka ''Kerio Firewall'') are known to interfere with TDM's lightgem, ''even when "disabled"''. To fix this problem, completely uninstall the firewall and get a different one instead.

Related [http://bugs.angua.at/view.php?id=543 #543]: Consider using glReadPixels for lightgem instead of named pipes.

==="COULD NOT FIND TDMLAUNCHER" when installing an FM===

If you receive this error message you should check the start-arguments of DOOM3.exe / tdmlauncher.exe. Arguments are stored in darkmod/dmargs.txt and a faulty syntax e.g. a missing "+" before a "set"-command, will lead to this error message. Steam users are advised to remove any launch-options from Doom.

===The sound lags behind the picture===

This seems to happen on some Linux Distributions with PulseAudio. Doom's sound engine defaults to ALSA, you can try to use OSS instead:

Add the following to your ''dmargs.txt'' (it is in ''~/.doom/darkmod/''):

+set s_driver oss

If your system does not provide OSS or a working OSS-emulation (try ''padsp ./tmdlauncher-linux''), reset this to ''best'' which means ALSA.

While OSS or ALSA deal directly with the sound hardware, PulseAudio is a soundserver that puts itself between the application (doom3) and ALSA. Your goal is to bypass the PA-part while playing TDM.

You can either disable the PulseAudio daemon temporarily or connect Doom directly to ALSA.

To disable PA, create a file named ''client.conf'' in ''~/.pulse'' which contains:

autospawn=no

Then open a terminal and type:

pulseaudio -k

When sound playback fails, make sure you have ''s_driver'' set to ''best'', and ''s_alsa_pcm'' to ''default''. When it works, you propably want to adjust volume settings outside TDM. Try ''alsamixer'' (in a terminal).

When you're finished playing, turn PA back on:

pulseaudio -D

starts the daemon. Changing ''autospawn'' to ''yes'' should prevent you from doing this manually after every reboot. :)

The other way, just bypassing PA, requires some knowledge about your sound hardware. Type

aplay -L

This gives you a long list of your ALSA playback devices, three lines for each, first line is ''<name>''. Choose the one with PCM Playback that your speakers are connected to and add

+set s_alsa_pcm <name>

to ''dmargs.txt''. If ''<name>'' is not convenient for you just try something like hw:1,0 if you know what you are doing, but be aware abstract designations like ''default'' will get "hijacked" by PA.

=== Changing the screen resolution/aspect ratio does nothing!? ===

These changes require a restart of Doom to work. Alternatively the command vid_restart can be issued at the console. It can take quite some time to execute this command, depending on whether or not you're already ingame. It will still be a lot faster than restarting and reloading the game though.

=== Disable Catalyst AI in recent AMD ATI drivers ===

From (at least) Catalyst versions 10.12 and beyond, the ability to disable Catalyst AI properly
has been changed or removed.

----

Rage3d and Guru3d have advised using "Radeon Pro" to address this.

Steps

* 1) Remove Catalyst Control Center (removing all ATI drivers recommended then re-install just the Display driver)
* 2) Download and install "Radeon Pro" [http://forums.guru3d.com/showthread.php?t=322031 Radeon Pro Thread at Guru3D]
* 3) Create a profile as follows:

<pre>
If you're using RadeonPro, create a profile for the game you want to disable Catalyst AI.
Right-click the newly created profile, keep left shift key pressed and choose
Open Location on context-menu, this will open the profile's XML definition.
Append a new line and add entry like this

<Property name="CatalystAI" value="0" />

Save the file and start the game. CatalystAI should be disabled.

I also recommend to open ___GlobalProfile.xml
(found on same directory where your profile is saved)
and look for "CatalystAI" entry, it must be equal to "1"
otherwise CatalystAI will be kept disabled after you exit your game.

CFX disabled by setting CatalystAI to 0
</pre>

Here's another alternate method for Windows users:

* 1) Obtain a copy of the free "ATI Tray Tools" by Ray Adams from [http://downloads.guru3d.com/download.php?det=733 Guru3d].

* 2) Install it into your Windows tray.

* 3) Right-click it.

* 4) Select Direct 3d -> Catalyst AI -> Off.

=== Disable Nvidia "Threaded Optimizations" ===

Many random crash behaviors seen by Nvidia users can be resolve by the following steps:

<pre>

Open Nvidia Control Panel ->

Manage 3D Settings ->

Bottom half of list locate "Threaded Optimization" <-- Set to NO / Off

Also set "Multi-display/Mixed GPU acceleration" to "Single display performance mode"

</pre>

=== Getting "Malloc Failure for #######" crash-to-desktop ===

Because Doom 3 is a 32-bit game, it can only utilize a certain amount of RAM. When Doom 3 needs more memory, but cannot allocate anymore, it crashes with an error saying something like
<pre>
Shutdown event system
--------------------------------------
malloc failure for 3145781
</pre>

If you run into malloc failures, it is suggested to try the following:

1) Edit your darkmod.cfg and use the following:
seta image_downSizeBump "1"
seta image_downSizeBumpLimit "256"

These will reduce the bumpmap size. Memory impact will be few hundred megabytes lower, at the expensee of very minor blurring of texture quality.

2) If the above does not help you it is recommended you try
seta image_downSize "1"
seta com_videoRam "512" (or however much video RAM you have).

These will reduce all texture sizes. Memory impact will be much lower, but the graphics are visually pixelated, depending on the com_videoRam number. But at least the mission will be more likely run with systems with low RAM.

A possible solution is to patch Doom3.exe with a [http://www.ntcore.com/4gb_patch.php 4GB Patcher] to allow the game to allocate more memory, but the TheDarkMod.exe should already be using large memory space.

=== Screen is Oversized in Fullscreen Mode (Image is too large to fit the screen area available) ===
Windows 7 Aero desktop is known to make the screen too large in fullscreen mode. This can be remedied by setting Windows 7 Aero to Basic.

This issue is discussed in more detail [http://forums.thedarkmod.com/topic/14622-oversized-title-screen-solved-caused-by-aero/ HERE].

== See also ==

* [[Known Bugs]]
* [[Gameplay]]

{{installation}} {{general}}

FAQ

2015-02-10T07:00:13Z

Demagogue: /* Windows 2000: freeaddrinfo cannot be found in WS2_32.DLL */

{{important|headline=Important|text=This FAQ relates to the full TDM release version only. For players of the pre-release demos such as '''[[Thief's Den]]''' and '''[[Saint_Lucia|Tears of Saint Lucia]]''' please refer to the '''[[FAQ (Demo Releases)|Demo FAQ]]'''.'''}}

== What do I need to play The Dark Mod? ==

With the release of TDM 2.0, you no longer need Doom 3 installed. The Dark Mod is completely standalone (and free!). You need only follow the installation instructions on the website to start playing the game.

== Supported Operating Systems ==

=== Which Windows versions can I use? ===

The following versions of windows have been tested and are known to work : Windows 2000, Windows XP, Windows Vista, Windows 7, Windows 8, Windows Server 2008, Windows Server 2003 in both 32bit and 64bit flavours.

==== Windows 8.1 Preview ====

Thus far, on Intel HD graphics, TDM will not start unless it is started in Windows 7 compatibility mode:

Right click "TheDarkMod.exe" choose "Properties", click the "Compatibility" tab and select Windows 7 from the dropdown
list.

This may not be representative of other graphic hardware and may be due to early Windows 8.1 driver support.

==== PAE Enabled ====

One user with Windows XP Pro SP3 and an AMD Phenom processor reported problems starting Doom 3 due to having PAE enabled.

[http://modetwo.net/darkmod/index.php?/topic/12471-error-doom-3/ Thread]

=== Does it run in Linux? ===
Yes, Linux is supported.

=== Does it run in 64 Bit Linux? ===
Yes, Linux 64 bit is supported. In addition to the steps above, you need 32 bit compatibility libraries, since Doom3 is 32 bit only:
* On '''SuSE''', they should be included.
* On Ubuntu/Kubuntu, install the package '''ia32'''.

For TDM after 1.0, this step should be '''no''' longer neccessary:

* Since you cannot install 32 bit libraries on a 64 bit system with the normal package manager, you should use [http://ubuntuforums.org/showthread.php?t=474790 getlibs] to install '''libmng''' and the boost filesystem lib:
:<code>getlibs libmng.so.1</code>
:<code>getlibs -l libboost-filesystem1.34.1</code>

=== What about Gentoo? ===
Yes. It's not "officially" supported (the team doesn't test it specifically), however several users have reported success running TDM under Gentoo.

=== What about Ubuntu 8.10? ===
Yes. As of this writing you will need to install the '''libboost-filesystem''' package.

=== GLIBCXX_3.4.9 errors ===

If you receive an error about <tt>GLIBCXX_3.4.9</tt>, delete or rename the files <code>/usr/local/games/doom3/libstdc++.so.6</code> and <code>/usr/local/games/doom3/libgcc_s.so.1.</code>

If this doesn't resolve the error and you have an old version of GCC, then you may have to upgrade. It has been [http://modetwo.net/darkmod/index.php?/topic/9982-the-dark-mod-doom3-in-linux/ confirmed] that, at least under Gentoo, GCC 4.1 does not work with TDM but GCC 4.3 and GCC 4.4 are compatible.

=== Does it run on Mac OS X?===
TDM 1.08 is supported, but 2.0 is not. See [[Installation]].

== Graphics ==

=== Does TDM support widescreen resolutions? ===

Yes. Choose "16:9" or "16:10" in the in-game ''Settings'' menu, and select the appropriate resolution. Note that you need to restart the game to have the new setting in effect.

If the native resolution of your wide screen monitor is not listed, you can enter it into '''DoomConfig.cfg''' by changing the following entries like so:

set r_mode "-1"
set r_customwidth "1280"
set r_customheight "800"
seta r_aspectratio "2" // means 16:10, "1" is 16:9, other ratios are not yet supporred

{{infobox|If you get performance problems, please consider using a lower resolution and taking a look at [[Performance Tweaks]].}}

==== What about TV resolutions like 1360x768? ====

If you have a wide-screen TV which uses any non-standard resolution, like 1360x768 (instead of 1366x768), then please use the following:

seta r_customWidth "1360"
seta r_customHeight "768"
seta r_mode "-1"
seta r_aspectratio 2
seta g_fov "100" // or any other suitable value

Alternatively, see the manual of your TV on the possibility to switch it to a "1:1" pixel mapping, or "monitor mode" or "computer mode".

Here is some background information: http://hd.engadget.com/2006/04/21/whats-the-deal-with-1366-x-768/

{{infobox|If you get performance problems, please consider using a lower resolution and taking a look at [[Performance Tweaks]].}}

== Troubleshooting ==

It is hard to answer questions on why something fails, because wildly different systems cause wildly different symptoms. If the following section does not help you, please ask at our [http://www.modetwo.net/darkmod forums].

For any solutions below that refer to "disabling Catalyst AI", if you discover you can not use ATI's tools to do so, alternate methods are discussed in [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] below.

=== Can't load saved games -- TDM gives error about "can't load .script" file ===

Make sure your folder is called "darkmod". If it isn't, rename it. That should make the problem go away. I've heard reports that having spaces in the names of any folders in the path can cause problems, but haven't confirmed it. Something to try if it still happens and your folder is already called "darkmod".

=== Updater (tdm_update.exe) closes almost as soon as it's started ===

See the [[Tdm_update#Updater_closes_almost_as_soon_as_it.27s_started|main article on tdm_update]].

=== Updater (tdm_update.exe) crashes at some point during the update ===

This can happen if the Darkmod folder is set to "read only". You fix it by right clicking on the folder, clicking properties, and unchecking the box that says "read only".

=== Windows 2000: freeaddrinfo cannot be found in WS2_32.DLL ===
Please refer to the main article [[TDM in Windows 2000]] to work around this problem.

===FM won't install manually===

If you are running Dark Mod under Linux and have edited the file darkmod/currentfm.txt this might prevent the FM from installing. This may be fixed in an update but apparently editing using notepad under Wine works OK.

=== FMs downloaded but don't show in menu list===

You have downloaded some FMs but they don't show on Dark Mod's New Missions list. Possible causes:

* You must not extract the pk4s or zip files but put them into the darkmod/fms folder (or alternatively you can create the FM folder in there eg, darkmod/fms/chalice for chalice.pk4 or chalice.zip.
* Early versions of Dark Mod cannot handle zip suffixes. Solution: rename to .pk4 or run tdm_update to get the latest version of Dark Mod.

=== FM downloaded but won't play ===

If you have downloaded an FM you might see it in the New Missions List but can't get it to play. These are almost always an install problem. These are some of the causes and cures:

FMs (fan missions) are archives and in early versions of Dark Mod MUST be suffixed .pk4 not zip. Apparently Internet Explorer 8 may change it from pk4 to zip during download without telling you. You need to rename it back if running an early version of Dark Mod else run tdm_update to update and then zip files are OK.

You do NOT need to extract the pk4 archives to install or play. Just download into or move the pk4 into the darkmod\fms folder. Optionally you can create a folder of the same name as the map and put it in there, eg, darkmod\fms\chalice but there is no need because Dark Mod will create that automatically. Just make sure your pk4 goes, unopened, into the fms folder, then run TheDarkMod.exe

If you have done the above but see for example, a blank objectives screen and no briefing then it is still almost certainly an install error. I recommend you do a clean sweep if in doubt:
* Exit Dark Mod
* Delete darkmod\currentfm.txt (this just uninstalls any FM)
* Move the pk4 into the darkmod\fms folder if it is not already there.
* Delete the darkmod\fms\FMname folder if any, eg, darkmod\fms\chalice. Don't worry if there isn't one; it will be created automatically later.

So all that is left is the pk4 in the fms folder. Now run TheDarkMod.exe. The FM should be in the list in the New Missions menu. Re-install it and you should now be able to play it.

=== The game hangs at Dark Mod screen/ locks up while turning on vsynch ===
Catalyst Control Center above 10.8 for ATI cards has a performance slider for V-Synch. Setting that slider to Quality (Always On)
fixes this issue. If set lower than quality and it is set to on in game it will freeze.
(tested specifically in CC 10-11)

=== The game crashes on load ===
Make sure that:
* Your system meets at least the minimum system specs.
* You have enough free main memory. Try closing a few running programs like Outlook, Anti-Virus or torrent clients.
* Nvidia "Threaded Optimizations" are causing Doom 3 Mod stability issues (see: [[#Disable Nvidia "Threaded Optimizations"|Disable Nvidia "Threaded Optimizations"]] )

If that doesn't fix it, you probably receive an error message referencing an "Unknown event" at startup, like the screenshot below illustrates.

[[Image:ErrorSetEntityRelation.jpg]]

Here are a couple of known problems and their solutions:
<ul>
<li>Sometimes, the procedure fails due to '''spaces in the installation path'''. Try extracting the gamex86.dll manually using Winzip or similar or install Doom 3 in a different directory.</li>
<li>You have a '''firewall''' installed that prevents the copy procedure, because since version 1.03, TDM has a built-in mission downloader. This misbehavior has been reported for the '''COMODO Firewall'''.</li>
</ul>
<li>It is also possible that an '''old version of gamex86.dll''' (or gamex86.so) is lying around in your Doom 3 folder. Delete it and try again.</li>
</ul>

=== Textures are missing, screen mostly black ===

[[Image:Tdm missing textures.jpg|right|240px|Black textures]]

Look into your '''darkmod.cfg''' inside your <tt>darkmod</tt> folder and check that the following settings are like shown below:

<pre style="max-width:35em">
seta image_usePrecompressedTextures "1"
seta image_useNormalCompression "2"
seta image_useAllFormats "1"
seta image_useCompression "0"
seta image_preload "1"
</pre>

=== Textures are missing, shadows are pitch black ===

Try disabling the AGP surface accelerator in DXDIAG.

=== Graphic Corruption ===

One report we had was for a Radeon ATI HD 4650, catalyst 10.9. This screen corruption as I understand it was heavy pixelation even on the menus. Closing down Xfire fixed it. "I fiddled with the xfire Doom 3 configuration through the xfire_games.ini, and determined it has to do with InGameFlags portion. For some reason the settings in that were interfering with doom 3, and after I removed some things from there, I was still able to run xfire, and doom 3 was still able to look proper."

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== The briefing is very fuzzy ===

Look into your '''DoomConfig.cfg''' inside your <tt>darkmod</tt> folder and check that the following settings are like shown below:

seta image_roundDown "1"
seta image_forceDownSize "0"
seta image_downSize "0"

=== The sky is corrupted ===

You either see black sky, or fragments of other textures. This seems only to happen on Geforce 6800 cards.

There are two fixes for this:

As a quick fix you can rename the following folder:

env/skyboxes/skybox_darkland_ne

to a different name. That will result in black sky.

Alternatively, edit the file <tt>materials/tdm_sky.mtr</tt> with '''Wordpad''' or a different editor and
find the sky material named '''textures/darkmod/nature/skybox/skybox_darkland_NE''':

<pre>
//Author: Dram
//skybox_ocean with ocean replaced with dark land
//Moon moved to north east by Fidcal
textures/darkmod/nature/skybox/skybox_darkland_NE
{
qer_editorimage env/skyboxes/skybox_ocean/ocean_ed
noFragment
noshadows
noimpact
nooverlays
forceOpaque
{
forceHighQuality
blend add
cameraCubeMap env/skyboxes/skybox_darkland_ne/darkland_NE
texgen skybox
texgen wobblesky .0 .0 .0
}
}
</pre>

In this declaration, comment out the line that reads '''forceHighQuality''' by adding <tt>//</tt> in front of it:

// forceHighQuality

That should fix the sky and make it render correctly.

=== The Sky rotates ===

This problem only affects FMs with a dynamic sky (eg, moving clouds etc.).

If you see the sky spinning it may be an ATI graphics card problem. One report says this was cured by turning off Catalyst AI. Also gives better loading times and cures [[#HDR-Lite Post-Processing problems|HDR-Lite Post-Processing Problems]].

If that doesn't fix it then try this. Note that it replaces dynamic sky with a static clear one so it might look odd in a stormy FM for example, but better than a spinning sky:

<pre>

* Create a new folder in your darkmod folder called materials.
* Within it create a plain text file named no_skybox.mtr.
* Paste in the following:

textures/smf/portal_sky
{
qer_editorimage env/skyboxes/skybox_ocean/ocean_ed
noFragment

noimpact
nooverlays
forceOpaque
noShadows
{
forceHighQuality
blend add
cameraCubeMap env/skyboxes/skybox_darkland_ne/darkland_NE
texgen skybox
texgen wobblesky .0 .0 .0
}
}

</pre>

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== HDR-Lite Post-Processing problems ===

Some owners of ATI graphics cards reported various artifacts when HDR-Lite Post-Processing was enabled. Among these artifacts are a distorted or upside-down screen and spinning sky. These can usually be fixed by disabling Catalyst AI, which also gives better loading times.

To turn off Catalyst AI, open your Catalyst control panel, go to 'graphics' at the top left, select '3d' from the dropdown list and on the new menu below, select 'AI'. Now select the 'Disable Catalyst A.I.' checkbox.

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

It has also been suspected that HDR-Lite Post-Processing may lead to [[#Underwater performance poor|poor performance underwater]], see next point:

===Underwater performance poor===

Some people suffer from very low framerates underwater with HDR-Lite Post-Processing enabled. Currently, the only known fix to this problem is to set '''g_doubleVision''' to 0 in the console. This however disables the doubleVision effect completely, so that there is no underwater-blur any more. The murkiness still remains though.

===Upside-down screen===

If you get an upside-down screen, you can either turn off Catalyst AI if you have an ATI card or try turning off HDR-Lite Post-Processing in the advanced video options.

To turn off Catalyst AI, open your Catalyst control panel, go to 'graphics' at the top left, select '3d' from the dropdown list and on the new menu below, select 'AI'. Now select the 'Disable Catalyst A.I.' checkbox.

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== The game is '''very''' slow! ===

If you get less than 10 FPS, or the game even stutters, please try this:

Look into your '''DoomConfig.cfg''' inside your <tt>darkmod</tt> folder and check that the
following settings are like shown below:

<pre style="max-width:35em">
seta image_usePrecompressedTextures "1"
seta image_useNormalCompression "2"
seta image_useAllFormats "1"
seta image_useCompression "1"
seta image_preload "1"
</pre>

If that doesn't help, your system might run out of memory. Either upgrade to more than 1 Gbyte memory,
or try to close other applications before playing.

Please see also the article about [[Performance Tweaks]] to improve the performance.

=== Slow loading times ===

If you find an FM is very slow to load it may be an ATI graphics card problem. One report says this was cured by turning off Catalyst AI. Also cures [[#HDR-Lite Post-Processing problems|HDR-Lite Post-Processing Problems]].

Changing the following settings to 0 will also reduce loading time, but be warned: if you have a lower-end system, poor graphics card, or low ram, you will likely notice a performance hit ingame since you will now be using uncompressed textures.
<pre style="max-width:35em">
seta image_useNormalCompression "0"
seta image_useCompression "0"
</pre>

===Game freezes for several seconds when opening doors===
The following problems :

A) "game freezes and loads some data from hard drive while opening doors"
B) "while loading mission you are returned to the menu and need to restart loading"

are often resolved by disabling EAX 4.0 HD in the Audio Settings menu.

===Game exits to menu after mission load, with renderpipe error in console===

* {{Red|Version 1.06 does not use named pipes. This is a depreciated issue.}}

'''Symptoms:''' Missions are installed properly and will load, but after they reach 100% you are returned to the main menu or objectives screen. If you open the console (Ctrl-Alt-~ on US keyboards), you see one/both of these errors:

ERROR: Failed to open \\.\pipe\dm_renderpipe

or

ERROR: idRenderSystemLocal::uncrop currentcrop <1

'''Solution:''' Some firewalls, notably ''Sunbelt Firewall'' (aka ''Kerio Firewall'') are known to interfere with TDM's lightgem, ''even when "disabled"''. To fix this problem, completely uninstall the firewall and get a different one instead.

Related [http://bugs.angua.at/view.php?id=543 #543]: Consider using glReadPixels for lightgem instead of named pipes.

==="COULD NOT FIND TDMLAUNCHER" when installing an FM===

If you receive this error message you should check the start-arguments of DOOM3.exe / tdmlauncher.exe. Arguments are stored in darkmod/dmargs.txt and a faulty syntax e.g. a missing "+" before a "set"-command, will lead to this error message. Steam users are advised to remove any launch-options from Doom.

===The sound lags behind the picture===

This seems to happen on some Linux Distributions with PulseAudio. Doom's sound engine defaults to ALSA, you can try to use OSS instead:

Add the following to your ''dmargs.txt'' (it is in ''~/.doom/darkmod/''):

+set s_driver oss

If your system does not provide OSS or a working OSS-emulation (try ''padsp ./tmdlauncher-linux''), reset this to ''best'' which means ALSA.

While OSS or ALSA deal directly with the sound hardware, PulseAudio is a soundserver that puts itself between the application (doom3) and ALSA. Your goal is to bypass the PA-part while playing TDM.

You can either disable the PulseAudio daemon temporarily or connect Doom directly to ALSA.

To disable PA, create a file named ''client.conf'' in ''~/.pulse'' which contains:

autospawn=no

Then open a terminal and type:

pulseaudio -k

When sound playback fails, make sure you have ''s_driver'' set to ''best'', and ''s_alsa_pcm'' to ''default''. When it works, you propably want to adjust volume settings outside TDM. Try ''alsamixer'' (in a terminal).

When you're finished playing, turn PA back on:

pulseaudio -D

starts the daemon. Changing ''autospawn'' to ''yes'' should prevent you from doing this manually after every reboot. :)

The other way, just bypassing PA, requires some knowledge about your sound hardware. Type

aplay -L

This gives you a long list of your ALSA playback devices, three lines for each, first line is ''<name>''. Choose the one with PCM Playback that your speakers are connected to and add

+set s_alsa_pcm <name>

to ''dmargs.txt''. If ''<name>'' is not convenient for you just try something like hw:1,0 if you know what you are doing, but be aware abstract designations like ''default'' will get "hijacked" by PA.

=== Changing the screen resolution/aspect ratio does nothing!? ===

These changes require a restart of Doom to work. Alternatively the command vid_restart can be issued at the console. It can take quite some time to execute this command, depending on whether or not you're already ingame. It will still be a lot faster than restarting and reloading the game though.

=== Disable Catalyst AI in recent AMD ATI drivers ===

From (at least) Catalyst versions 10.12 and beyond, the ability to disable Catalyst AI properly
has been changed or removed.

----

Rage3d and Guru3d have advised using "Radeon Pro" to address this.

Steps

* 1) Remove Catalyst Control Center (removing all ATI drivers recommended then re-install just the Display driver)
* 2) Download and install "Radeon Pro" [http://forums.guru3d.com/showthread.php?t=322031 Radeon Pro Thread at Guru3D]
* 3) Create a profile as follows:

<pre>
If you're using RadeonPro, create a profile for the game you want to disable Catalyst AI.
Right-click the newly created profile, keep left shift key pressed and choose
Open Location on context-menu, this will open the profile's XML definition.
Append a new line and add entry like this

<Property name="CatalystAI" value="0" />

Save the file and start the game. CatalystAI should be disabled.

I also recommend to open ___GlobalProfile.xml
(found on same directory where your profile is saved)
and look for "CatalystAI" entry, it must be equal to "1"
otherwise CatalystAI will be kept disabled after you exit your game.

CFX disabled by setting CatalystAI to 0
</pre>

Here's another alternate method for Windows users:

* 1) Obtain a copy of the free "ATI Tray Tools" by Ray Adams from [http://downloads.guru3d.com/download.php?det=733 Guru3d].

* 2) Install it into your Windows tray.

* 3) Right-click it.

* 4) Select Direct 3d -> Catalyst AI -> Off.

=== Disable Nvidia "Threaded Optimizations" ===

Many random crash behaviors seen by Nvidia users can be resolve by the following steps:

<pre>

Open Nvidia Control Panel ->

Manage 3D Settings ->

Bottom half of list locate "Threaded Optimization" <-- Set to NO / Off

Also set "Multi-display/Mixed GPU acceleration" to "Single display performance mode"

</pre>

=== Getting "Malloc Failure for #######" crash-to-desktop ===

Because Doom 3 is a 32-bit game, it can only utilize a certain amount of RAM. When Doom 3 needs more memory, but cannot allocate anymore, it crashes with an error saying something like
<pre>
Shutdown event system
--------------------------------------
malloc failure for 3145781
</pre>

If you run into malloc failures, it is suggested to try the following:

1) Edit your darkmod.cfg and use the following:
seta image_downSizeBump "1"
seta image_downSizeBumpLimit "256"

These will reduce the bumpmap size. Memory impact will be few hundred megabytes lower, at the expensee of very minor blurring of texture quality.

2) If the above does not help you it is recommended you try
seta image_downSize "1"
seta com_videoRam "512" (or however much video RAM you have).

These will reduce all texture sizes. Memory impact will be much lower, but the graphics are visually pixelated, depending on the com_videoRam number. But at least the mission will be more likely run with systems with low RAM.

A possible solution is to patch Doom3.exe with a [http://www.ntcore.com/4gb_patch.php 4GB Patcher] to allow the game to allocate more memory, but the TheDarkMod.exe should already be using large memory space.

=== Screen is Oversized in Fullscreen Mode (Image is too large to fit the screen area available) ===
Windows 7 Aero desktop is known to make the screen too large in fullscreen mode. This can be remedied by setting Windows 7 Aero to Basic.

This issue is discussed in more detail [http://forums.thedarkmod.com/topic/14622-oversized-title-screen-solved-caused-by-aero/ HERE].

== See also ==

* [[Known Bugs]]
* [[Gameplay]]

{{installation}} {{general}}

FAQ

2015-02-10T06:59:53Z

Demagogue: /* Updater (tdm_update.exe) crashes at some point during the update */

{{important|headline=Important|text=This FAQ relates to the full TDM release version only. For players of the pre-release demos such as '''[[Thief's Den]]''' and '''[[Saint_Lucia|Tears of Saint Lucia]]''' please refer to the '''[[FAQ (Demo Releases)|Demo FAQ]]'''.'''}}

== What do I need to play The Dark Mod? ==

With the release of TDM 2.0, you no longer need Doom 3 installed. The Dark Mod is completely standalone (and free!). You need only follow the installation instructions on the website to start playing the game.

== Supported Operating Systems ==

=== Which Windows versions can I use? ===

The following versions of windows have been tested and are known to work : Windows 2000, Windows XP, Windows Vista, Windows 7, Windows 8, Windows Server 2008, Windows Server 2003 in both 32bit and 64bit flavours.

==== Windows 8.1 Preview ====

Thus far, on Intel HD graphics, TDM will not start unless it is started in Windows 7 compatibility mode:

Right click "TheDarkMod.exe" choose "Properties", click the "Compatibility" tab and select Windows 7 from the dropdown
list.

This may not be representative of other graphic hardware and may be due to early Windows 8.1 driver support.

==== PAE Enabled ====

One user with Windows XP Pro SP3 and an AMD Phenom processor reported problems starting Doom 3 due to having PAE enabled.

[http://modetwo.net/darkmod/index.php?/topic/12471-error-doom-3/ Thread]

=== Does it run in Linux? ===
Yes, Linux is supported.

=== Does it run in 64 Bit Linux? ===
Yes, Linux 64 bit is supported. In addition to the steps above, you need 32 bit compatibility libraries, since Doom3 is 32 bit only:
* On '''SuSE''', they should be included.
* On Ubuntu/Kubuntu, install the package '''ia32'''.

For TDM after 1.0, this step should be '''no''' longer neccessary:

* Since you cannot install 32 bit libraries on a 64 bit system with the normal package manager, you should use [http://ubuntuforums.org/showthread.php?t=474790 getlibs] to install '''libmng''' and the boost filesystem lib:
:<code>getlibs libmng.so.1</code>
:<code>getlibs -l libboost-filesystem1.34.1</code>

=== What about Gentoo? ===
Yes. It's not "officially" supported (the team doesn't test it specifically), however several users have reported success running TDM under Gentoo.

=== What about Ubuntu 8.10? ===
Yes. As of this writing you will need to install the '''libboost-filesystem''' package.

=== GLIBCXX_3.4.9 errors ===

If you receive an error about <tt>GLIBCXX_3.4.9</tt>, delete or rename the files <code>/usr/local/games/doom3/libstdc++.so.6</code> and <code>/usr/local/games/doom3/libgcc_s.so.1.</code>

If this doesn't resolve the error and you have an old version of GCC, then you may have to upgrade. It has been [http://modetwo.net/darkmod/index.php?/topic/9982-the-dark-mod-doom3-in-linux/ confirmed] that, at least under Gentoo, GCC 4.1 does not work with TDM but GCC 4.3 and GCC 4.4 are compatible.

=== Does it run on Mac OS X?===
TDM 1.08 is supported, but 2.0 is not. See [[Installation]].

== Graphics ==

=== Does TDM support widescreen resolutions? ===

Yes. Choose "16:9" or "16:10" in the in-game ''Settings'' menu, and select the appropriate resolution. Note that you need to restart the game to have the new setting in effect.

If the native resolution of your wide screen monitor is not listed, you can enter it into '''DoomConfig.cfg''' by changing the following entries like so:

set r_mode "-1"
set r_customwidth "1280"
set r_customheight "800"
seta r_aspectratio "2" // means 16:10, "1" is 16:9, other ratios are not yet supporred

{{infobox|If you get performance problems, please consider using a lower resolution and taking a look at [[Performance Tweaks]].}}

==== What about TV resolutions like 1360x768? ====

If you have a wide-screen TV which uses any non-standard resolution, like 1360x768 (instead of 1366x768), then please use the following:

seta r_customWidth "1360"
seta r_customHeight "768"
seta r_mode "-1"
seta r_aspectratio 2
seta g_fov "100" // or any other suitable value

Alternatively, see the manual of your TV on the possibility to switch it to a "1:1" pixel mapping, or "monitor mode" or "computer mode".

Here is some background information: http://hd.engadget.com/2006/04/21/whats-the-deal-with-1366-x-768/

{{infobox|If you get performance problems, please consider using a lower resolution and taking a look at [[Performance Tweaks]].}}

== Troubleshooting ==

It is hard to answer questions on why something fails, because wildly different systems cause wildly different symptoms. If the following section does not help you, please ask at our [http://www.modetwo.net/darkmod forums].

For any solutions below that refer to "disabling Catalyst AI", if you discover you can not use ATI's tools to do so, alternate methods are discussed in [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] below.

=== Can't load saved games -- TDM gives error about "can't load .script" file ===

Make sure your folder is called "darkmod". If it isn't, rename it. That should make the problem go away. I've heard reports that having spaces in the names of any folders in the path can cause problems, but haven't confirmed it. Something to try if it still happens and your folder is already called "darkmod".

=== Updater (tdm_update.exe) closes almost as soon as it's started ===

See the [[Tdm_update#Updater_closes_almost_as_soon_as_it.27s_started|main article on tdm_update]].

=== Updater (tdm_update.exe) crashes at some point during the update ===

This can happen if the Darkmod folder is set to "read only". You fix it by right clicking on the folder, clicking properties, and unchecking the box that says "read only".

=== Windows 2000: freeaddrinfo cannot be found in WS2_32.DLL ===
Please refer to the main article [[TDM in Windows 2000]] to work around this problem.

===FM won't install manually===

If you are running Dark Mod under Linux and have edited the file darkmod/currentfm.txt this might prevent the FM from installing. This may be fixed in an update but apparently editing using notepad under Wine works OK.

=== FMs downloaded but don't show in menu list===

You have downloaded some FMs but they don't show on Dark Mod's New Missions list. Possible causes:

* You must not extract the pk4s or zip files but put them into the darkmod/fms folder (or alternatively you can create the FM folder in there eg, darkmod/fms/chalice for chalice.pk4 or chalice.zip.
* Early versions of Dark Mod cannot handle zip suffixes. Solution: rename to .pk4 or run tdm_update to get the latest version of Dark Mod.

=== FM downloaded but won't play ===

If you have downloaded an FM you might see it in the New Missions List but can't get it to play. These are almost always an install problem. These are some of the causes and cures:

FMs (fan missions) are archives and in early versions of Dark Mod MUST be suffixed .pk4 not zip. Apparently Internet Explorer 8 may change it from pk4 to zip during download without telling you. You need to rename it back if running an early version of Dark Mod else run tdm_update to update and then zip files are OK.

You do NOT need to extract the pk4 archives to install or play. Just download into or move the pk4 into the darkmod\fms folder. Optionally you can create a folder of the same name as the map and put it in there, eg, darkmod\fms\chalice but there is no need because Dark Mod will create that automatically. Just make sure your pk4 goes, unopened, into the fms folder, then run TheDarkMod.exe

If you have done the above but see for example, a blank objectives screen and no briefing then it is still almost certainly an install error. I recommend you do a clean sweep if in doubt:
* Exit Dark Mod
* Delete darkmod\currentfm.txt (this just uninstalls any FM)
* Move the pk4 into the darkmod\fms folder if it is not already there.
* Delete the darkmod\fms\FMname folder if any, eg, darkmod\fms\chalice. Don't worry if there isn't one; it will be created automatically later.

So all that is left is the pk4 in the fms folder. Now run TheDarkMod.exe. The FM should be in the list in the New Missions menu. Re-install it and you should now be able to play it.

=== The game hangs at Dark Mod screen/ locks up while turning on vsynch ===
Catalyst Control Center above 10.8 for ATI cards has a performance slider for V-Synch. Setting that slider to Quality (Always On)
fixes this issue. If set lower than quality and it is set to on in game it will freeze.
(tested specifically in CC 10-11)

=== The game crashes on load ===
Make sure that:
* Your system meets at least the minimum system specs.
* You have enough free main memory. Try closing a few running programs like Outlook, Anti-Virus or torrent clients.
* Nvidia "Threaded Optimizations" are causing Doom 3 Mod stability issues (see: [[#Disable Nvidia "Threaded Optimizations"|Disable Nvidia "Threaded Optimizations"]] )

If that doesn't fix it, you probably receive an error message referencing an "Unknown event" at startup, like the screenshot below illustrates.

[[Image:ErrorSetEntityRelation.jpg]]

Here are a couple of known problems and their solutions:
<ul>
<li>Sometimes, the procedure fails due to '''spaces in the installation path'''. Try extracting the gamex86.dll manually using Winzip or similar or install Doom 3 in a different directory.</li>
<li>You have a '''firewall''' installed that prevents the copy procedure, because since version 1.03, TDM has a built-in mission downloader. This misbehavior has been reported for the '''COMODO Firewall'''.</li>
</ul>
<li>It is also possible that an '''old version of gamex86.dll''' (or gamex86.so) is lying around in your Doom 3 folder. Delete it and try again.</li>
</ul>

=== Textures are missing, screen mostly black ===

[[Image:Tdm missing textures.jpg|right|240px|Black textures]]

Look into your '''darkmod.cfg''' inside your <tt>darkmod</tt> folder and check that the following settings are like shown below:

<pre style="max-width:35em">
seta image_usePrecompressedTextures "1"
seta image_useNormalCompression "2"
seta image_useAllFormats "1"
seta image_useCompression "0"
seta image_preload "1"
</pre>

=== Textures are missing, shadows are pitch black ===

Try disabling the AGP surface accelerator in DXDIAG.

=== Graphic Corruption ===

One report we had was for a Radeon ATI HD 4650, catalyst 10.9. This screen corruption as I understand it was heavy pixelation even on the menus. Closing down Xfire fixed it. "I fiddled with the xfire Doom 3 configuration through the xfire_games.ini, and determined it has to do with InGameFlags portion. For some reason the settings in that were interfering with doom 3, and after I removed some things from there, I was still able to run xfire, and doom 3 was still able to look proper."

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== The briefing is very fuzzy ===

Look into your '''DoomConfig.cfg''' inside your <tt>darkmod</tt> folder and check that the following settings are like shown below:

seta image_roundDown "1"
seta image_forceDownSize "0"
seta image_downSize "0"

=== The sky is corrupted ===

You either see black sky, or fragments of other textures. This seems only to happen on Geforce 6800 cards.

There are two fixes for this:

As a quick fix you can rename the following folder:

env/skyboxes/skybox_darkland_ne

to a different name. That will result in black sky.

Alternatively, edit the file <tt>materials/tdm_sky.mtr</tt> with '''Wordpad''' or a different editor and
find the sky material named '''textures/darkmod/nature/skybox/skybox_darkland_NE''':

<pre>
//Author: Dram
//skybox_ocean with ocean replaced with dark land
//Moon moved to north east by Fidcal
textures/darkmod/nature/skybox/skybox_darkland_NE
{
qer_editorimage env/skyboxes/skybox_ocean/ocean_ed
noFragment
noshadows
noimpact
nooverlays
forceOpaque
{
forceHighQuality
blend add
cameraCubeMap env/skyboxes/skybox_darkland_ne/darkland_NE
texgen skybox
texgen wobblesky .0 .0 .0
}
}
</pre>

In this declaration, comment out the line that reads '''forceHighQuality''' by adding <tt>//</tt> in front of it:

// forceHighQuality

That should fix the sky and make it render correctly.

=== The Sky rotates ===

This problem only affects FMs with a dynamic sky (eg, moving clouds etc.).

If you see the sky spinning it may be an ATI graphics card problem. One report says this was cured by turning off Catalyst AI. Also gives better loading times and cures [[#HDR-Lite Post-Processing problems|HDR-Lite Post-Processing Problems]].

If that doesn't fix it then try this. Note that it replaces dynamic sky with a static clear one so it might look odd in a stormy FM for example, but better than a spinning sky:

<pre>

* Create a new folder in your darkmod folder called materials.
* Within it create a plain text file named no_skybox.mtr.
* Paste in the following:

textures/smf/portal_sky
{
qer_editorimage env/skyboxes/skybox_ocean/ocean_ed
noFragment

noimpact
nooverlays
forceOpaque
noShadows
{
forceHighQuality
blend add
cameraCubeMap env/skyboxes/skybox_darkland_ne/darkland_NE
texgen skybox
texgen wobblesky .0 .0 .0
}
}

</pre>

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== HDR-Lite Post-Processing problems ===

Some owners of ATI graphics cards reported various artifacts when HDR-Lite Post-Processing was enabled. Among these artifacts are a distorted or upside-down screen and spinning sky. These can usually be fixed by disabling Catalyst AI, which also gives better loading times.

To turn off Catalyst AI, open your Catalyst control panel, go to 'graphics' at the top left, select '3d' from the dropdown list and on the new menu below, select 'AI'. Now select the 'Disable Catalyst A.I.' checkbox.

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

It has also been suspected that HDR-Lite Post-Processing may lead to [[#Underwater performance poor|poor performance underwater]], see next point:

===Underwater performance poor===

Some people suffer from very low framerates underwater with HDR-Lite Post-Processing enabled. Currently, the only known fix to this problem is to set '''g_doubleVision''' to 0 in the console. This however disables the doubleVision effect completely, so that there is no underwater-blur any more. The murkiness still remains though.

===Upside-down screen===

If you get an upside-down screen, you can either turn off Catalyst AI if you have an ATI card or try turning off HDR-Lite Post-Processing in the advanced video options.

To turn off Catalyst AI, open your Catalyst control panel, go to 'graphics' at the top left, select '3d' from the dropdown list and on the new menu below, select 'AI'. Now select the 'Disable Catalyst A.I.' checkbox.

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== The game is '''very''' slow! ===

If you get less than 10 FPS, or the game even stutters, please try this:

Look into your '''DoomConfig.cfg''' inside your <tt>darkmod</tt> folder and check that the
following settings are like shown below:

<pre style="max-width:35em">
seta image_usePrecompressedTextures "1"
seta image_useNormalCompression "2"
seta image_useAllFormats "1"
seta image_useCompression "1"
seta image_preload "1"
</pre>

If that doesn't help, your system might run out of memory. Either upgrade to more than 1 Gbyte memory,
or try to close other applications before playing.

Please see also the article about [[Performance Tweaks]] to improve the performance.

=== Slow loading times ===

If you find an FM is very slow to load it may be an ATI graphics card problem. One report says this was cured by turning off Catalyst AI. Also cures [[#HDR-Lite Post-Processing problems|HDR-Lite Post-Processing Problems]].

Changing the following settings to 0 will also reduce loading time, but be warned: if you have a lower-end system, poor graphics card, or low ram, you will likely notice a performance hit ingame since you will now be using uncompressed textures.
<pre style="max-width:35em">
seta image_useNormalCompression "0"
seta image_useCompression "0"
</pre>

===Game freezes for several seconds when opening doors===
The following problems :

A) "game freezes and loads some data from hard drive while opening doors"
B) "while loading mission you are returned to the menu and need to restart loading"

are often resolved by disabling EAX 4.0 HD in the Audio Settings menu.

===Game exits to menu after mission load, with renderpipe error in console===

* {{Red|Version 1.06 does not use named pipes. This is a depreciated issue.}}

'''Symptoms:''' Missions are installed properly and will load, but after they reach 100% you are returned to the main menu or objectives screen. If you open the console (Ctrl-Alt-~ on US keyboards), you see one/both of these errors:

ERROR: Failed to open \\.\pipe\dm_renderpipe

or

ERROR: idRenderSystemLocal::uncrop currentcrop <1

'''Solution:''' Some firewalls, notably ''Sunbelt Firewall'' (aka ''Kerio Firewall'') are known to interfere with TDM's lightgem, ''even when "disabled"''. To fix this problem, completely uninstall the firewall and get a different one instead.

Related [http://bugs.angua.at/view.php?id=543 #543]: Consider using glReadPixels for lightgem instead of named pipes.

==="COULD NOT FIND TDMLAUNCHER" when installing an FM===

If you receive this error message you should check the start-arguments of DOOM3.exe / tdmlauncher.exe. Arguments are stored in darkmod/dmargs.txt and a faulty syntax e.g. a missing "+" before a "set"-command, will lead to this error message. Steam users are advised to remove any launch-options from Doom.

===The sound lags behind the picture===

This seems to happen on some Linux Distributions with PulseAudio. Doom's sound engine defaults to ALSA, you can try to use OSS instead:

Add the following to your ''dmargs.txt'' (it is in ''~/.doom/darkmod/''):

+set s_driver oss

If your system does not provide OSS or a working OSS-emulation (try ''padsp ./tmdlauncher-linux''), reset this to ''best'' which means ALSA.

While OSS or ALSA deal directly with the sound hardware, PulseAudio is a soundserver that puts itself between the application (doom3) and ALSA. Your goal is to bypass the PA-part while playing TDM.

You can either disable the PulseAudio daemon temporarily or connect Doom directly to ALSA.

To disable PA, create a file named ''client.conf'' in ''~/.pulse'' which contains:

autospawn=no

Then open a terminal and type:

pulseaudio -k

When sound playback fails, make sure you have ''s_driver'' set to ''best'', and ''s_alsa_pcm'' to ''default''. When it works, you propably want to adjust volume settings outside TDM. Try ''alsamixer'' (in a terminal).

When you're finished playing, turn PA back on:

pulseaudio -D

starts the daemon. Changing ''autospawn'' to ''yes'' should prevent you from doing this manually after every reboot. :)

The other way, just bypassing PA, requires some knowledge about your sound hardware. Type

aplay -L

This gives you a long list of your ALSA playback devices, three lines for each, first line is ''<name>''. Choose the one with PCM Playback that your speakers are connected to and add

+set s_alsa_pcm <name>

to ''dmargs.txt''. If ''<name>'' is not convenient for you just try something like hw:1,0 if you know what you are doing, but be aware abstract designations like ''default'' will get "hijacked" by PA.

=== Changing the screen resolution/aspect ratio does nothing!? ===

These changes require a restart of Doom to work. Alternatively the command vid_restart can be issued at the console. It can take quite some time to execute this command, depending on whether or not you're already ingame. It will still be a lot faster than restarting and reloading the game though.

=== Disable Catalyst AI in recent AMD ATI drivers ===

From (at least) Catalyst versions 10.12 and beyond, the ability to disable Catalyst AI properly
has been changed or removed.

----

Rage3d and Guru3d have advised using "Radeon Pro" to address this.

Steps

* 1) Remove Catalyst Control Center (removing all ATI drivers recommended then re-install just the Display driver)
* 2) Download and install "Radeon Pro" [http://forums.guru3d.com/showthread.php?t=322031 Radeon Pro Thread at Guru3D]
* 3) Create a profile as follows:

<pre>
If you're using RadeonPro, create a profile for the game you want to disable Catalyst AI.
Right-click the newly created profile, keep left shift key pressed and choose
Open Location on context-menu, this will open the profile's XML definition.
Append a new line and add entry like this

<Property name="CatalystAI" value="0" />

Save the file and start the game. CatalystAI should be disabled.

I also recommend to open ___GlobalProfile.xml
(found on same directory where your profile is saved)
and look for "CatalystAI" entry, it must be equal to "1"
otherwise CatalystAI will be kept disabled after you exit your game.

CFX disabled by setting CatalystAI to 0
</pre>

Here's another alternate method for Windows users:

* 1) Obtain a copy of the free "ATI Tray Tools" by Ray Adams from [http://downloads.guru3d.com/download.php?det=733 Guru3d].

* 2) Install it into your Windows tray.

* 3) Right-click it.

* 4) Select Direct 3d -> Catalyst AI -> Off.

=== Disable Nvidia "Threaded Optimizations" ===

Many random crash behaviors seen by Nvidia users can be resolve by the following steps:

<pre>

Open Nvidia Control Panel ->

Manage 3D Settings ->

Bottom half of list locate "Threaded Optimization" <-- Set to NO / Off

Also set "Multi-display/Mixed GPU acceleration" to "Single display performance mode"

</pre>

=== Getting "Malloc Failure for #######" crash-to-desktop ===

Because Doom 3 is a 32-bit game, it can only utilize a certain amount of RAM. When Doom 3 needs more memory, but cannot allocate anymore, it crashes with an error saying something like
<pre>
Shutdown event system
--------------------------------------
malloc failure for 3145781
</pre>

If you run into malloc failures, it is suggested to try the following:

1) Edit your darkmod.cfg and use the following:
seta image_downSizeBump "1"
seta image_downSizeBumpLimit "256"

These will reduce the bumpmap size. Memory impact will be few hundred megabytes lower, at the expensee of very minor blurring of texture quality.

2) If the above does not help you it is recommended you try
seta image_downSize "1"
seta com_videoRam "512" (or however much video RAM you have).

These will reduce all texture sizes. Memory impact will be much lower, but the graphics are visually pixelated, depending on the com_videoRam number. But at least the mission will be more likely run with systems with low RAM.

A possible solution is to patch Doom3.exe with a [http://www.ntcore.com/4gb_patch.php 4GB Patcher] to allow the game to allocate more memory, but the TheDarkMod.exe should already be using large memory space.

=== Screen is Oversized in Fullscreen Mode (Image is too large to fit the screen area available) ===
Windows 7 Aero desktop is known to make the screen too large in fullscreen mode. This can be remedied by setting Windows 7 Aero to Basic.

This issue is discussed in more detail [http://forums.thedarkmod.com/topic/14622-oversized-title-screen-solved-caused-by-aero/ HERE].

== See also ==

* [[Known Bugs]]
* [[Gameplay]]

{{installation}} {{general}}

FAQ

2015-02-10T06:59:24Z

Demagogue: /* Updater (tdm_update.exe) closes almost as soon as it's started */

{{important|headline=Important|text=This FAQ relates to the full TDM release version only. For players of the pre-release demos such as '''[[Thief's Den]]''' and '''[[Saint_Lucia|Tears of Saint Lucia]]''' please refer to the '''[[FAQ (Demo Releases)|Demo FAQ]]'''.'''}}

== What do I need to play The Dark Mod? ==

With the release of TDM 2.0, you no longer need Doom 3 installed. The Dark Mod is completely standalone (and free!). You need only follow the installation instructions on the website to start playing the game.

== Supported Operating Systems ==

=== Which Windows versions can I use? ===

The following versions of windows have been tested and are known to work : Windows 2000, Windows XP, Windows Vista, Windows 7, Windows 8, Windows Server 2008, Windows Server 2003 in both 32bit and 64bit flavours.

==== Windows 8.1 Preview ====

Thus far, on Intel HD graphics, TDM will not start unless it is started in Windows 7 compatibility mode:

Right click "TheDarkMod.exe" choose "Properties", click the "Compatibility" tab and select Windows 7 from the dropdown
list.

This may not be representative of other graphic hardware and may be due to early Windows 8.1 driver support.

==== PAE Enabled ====

One user with Windows XP Pro SP3 and an AMD Phenom processor reported problems starting Doom 3 due to having PAE enabled.

[http://modetwo.net/darkmod/index.php?/topic/12471-error-doom-3/ Thread]

=== Does it run in Linux? ===
Yes, Linux is supported.

=== Does it run in 64 Bit Linux? ===
Yes, Linux 64 bit is supported. In addition to the steps above, you need 32 bit compatibility libraries, since Doom3 is 32 bit only:
* On '''SuSE''', they should be included.
* On Ubuntu/Kubuntu, install the package '''ia32'''.

For TDM after 1.0, this step should be '''no''' longer neccessary:

* Since you cannot install 32 bit libraries on a 64 bit system with the normal package manager, you should use [http://ubuntuforums.org/showthread.php?t=474790 getlibs] to install '''libmng''' and the boost filesystem lib:
:<code>getlibs libmng.so.1</code>
:<code>getlibs -l libboost-filesystem1.34.1</code>

=== What about Gentoo? ===
Yes. It's not "officially" supported (the team doesn't test it specifically), however several users have reported success running TDM under Gentoo.

=== What about Ubuntu 8.10? ===
Yes. As of this writing you will need to install the '''libboost-filesystem''' package.

=== GLIBCXX_3.4.9 errors ===

If you receive an error about <tt>GLIBCXX_3.4.9</tt>, delete or rename the files <code>/usr/local/games/doom3/libstdc++.so.6</code> and <code>/usr/local/games/doom3/libgcc_s.so.1.</code>

If this doesn't resolve the error and you have an old version of GCC, then you may have to upgrade. It has been [http://modetwo.net/darkmod/index.php?/topic/9982-the-dark-mod-doom3-in-linux/ confirmed] that, at least under Gentoo, GCC 4.1 does not work with TDM but GCC 4.3 and GCC 4.4 are compatible.

=== Does it run on Mac OS X?===
TDM 1.08 is supported, but 2.0 is not. See [[Installation]].

== Graphics ==

=== Does TDM support widescreen resolutions? ===

Yes. Choose "16:9" or "16:10" in the in-game ''Settings'' menu, and select the appropriate resolution. Note that you need to restart the game to have the new setting in effect.

If the native resolution of your wide screen monitor is not listed, you can enter it into '''DoomConfig.cfg''' by changing the following entries like so:

set r_mode "-1"
set r_customwidth "1280"
set r_customheight "800"
seta r_aspectratio "2" // means 16:10, "1" is 16:9, other ratios are not yet supporred

{{infobox|If you get performance problems, please consider using a lower resolution and taking a look at [[Performance Tweaks]].}}

==== What about TV resolutions like 1360x768? ====

If you have a wide-screen TV which uses any non-standard resolution, like 1360x768 (instead of 1366x768), then please use the following:

seta r_customWidth "1360"
seta r_customHeight "768"
seta r_mode "-1"
seta r_aspectratio 2
seta g_fov "100" // or any other suitable value

Alternatively, see the manual of your TV on the possibility to switch it to a "1:1" pixel mapping, or "monitor mode" or "computer mode".

Here is some background information: http://hd.engadget.com/2006/04/21/whats-the-deal-with-1366-x-768/

{{infobox|If you get performance problems, please consider using a lower resolution and taking a look at [[Performance Tweaks]].}}

== Troubleshooting ==

It is hard to answer questions on why something fails, because wildly different systems cause wildly different symptoms. If the following section does not help you, please ask at our [http://www.modetwo.net/darkmod forums].

For any solutions below that refer to "disabling Catalyst AI", if you discover you can not use ATI's tools to do so, alternate methods are discussed in [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] below.

=== Can't load saved games -- TDM gives error about "can't load .script" file ===

Make sure your folder is called "darkmod". If it isn't, rename it. That should make the problem go away. I've heard reports that having spaces in the names of any folders in the path can cause problems, but haven't confirmed it. Something to try if it still happens and your folder is already called "darkmod".

=== Updater (tdm_update.exe) closes almost as soon as it's started ===

See the [[Tdm_update#Updater_closes_almost_as_soon_as_it.27s_started|main article on tdm_update]].

=== Updater (tdm_update.exe) crashes at some point during the update ===

This can happen if the Darkmod folder is set to "read only". You fix it by right clicking on the folder, clicking properties, and unchecking the box that says "read only".

=== Windows 2000: freeaddrinfo cannot be found in WS2_32.DLL ===
Please refer to the main article [[TDM in Windows 2000]] to work around this problem.

===FM won't install manually===

If you are running Dark Mod under Linux and have edited the file darkmod/currentfm.txt this might prevent the FM from installing. This may be fixed in an update but apparently editing using notepad under Wine works OK.

=== FMs downloaded but don't show in menu list===

You have downloaded some FMs but they don't show on Dark Mod's New Missions list. Possible causes:

* You must not extract the pk4s or zip files but put them into the darkmod/fms folder (or alternatively you can create the FM folder in there eg, darkmod/fms/chalice for chalice.pk4 or chalice.zip.
* Early versions of Dark Mod cannot handle zip suffixes. Solution: rename to .pk4 or run tdm_update to get the latest version of Dark Mod.

=== FM downloaded but won't play ===

If you have downloaded an FM you might see it in the New Missions List but can't get it to play. These are almost always an install problem. These are some of the causes and cures:

FMs (fan missions) are archives and in early versions of Dark Mod MUST be suffixed .pk4 not zip. Apparently Internet Explorer 8 may change it from pk4 to zip during download without telling you. You need to rename it back if running an early version of Dark Mod else run tdm_update to update and then zip files are OK.

You do NOT need to extract the pk4 archives to install or play. Just download into or move the pk4 into the darkmod\fms folder. Optionally you can create a folder of the same name as the map and put it in there, eg, darkmod\fms\chalice but there is no need because Dark Mod will create that automatically. Just make sure your pk4 goes, unopened, into the fms folder, then run TheDarkMod.exe

If you have done the above but see for example, a blank objectives screen and no briefing then it is still almost certainly an install error. I recommend you do a clean sweep if in doubt:
* Exit Dark Mod
* Delete darkmod\currentfm.txt (this just uninstalls any FM)
* Move the pk4 into the darkmod\fms folder if it is not already there.
* Delete the darkmod\fms\FMname folder if any, eg, darkmod\fms\chalice. Don't worry if there isn't one; it will be created automatically later.

So all that is left is the pk4 in the fms folder. Now run TheDarkMod.exe. The FM should be in the list in the New Missions menu. Re-install it and you should now be able to play it.

=== The game hangs at Dark Mod screen/ locks up while turning on vsynch ===
Catalyst Control Center above 10.8 for ATI cards has a performance slider for V-Synch. Setting that slider to Quality (Always On)
fixes this issue. If set lower than quality and it is set to on in game it will freeze.
(tested specifically in CC 10-11)

=== The game crashes on load ===
Make sure that:
* Your system meets at least the minimum system specs.
* You have enough free main memory. Try closing a few running programs like Outlook, Anti-Virus or torrent clients.
* Nvidia "Threaded Optimizations" are causing Doom 3 Mod stability issues (see: [[#Disable Nvidia "Threaded Optimizations"|Disable Nvidia "Threaded Optimizations"]] )

If that doesn't fix it, you probably receive an error message referencing an "Unknown event" at startup, like the screenshot below illustrates.

[[Image:ErrorSetEntityRelation.jpg]]

Here are a couple of known problems and their solutions:
<ul>
<li>Sometimes, the procedure fails due to '''spaces in the installation path'''. Try extracting the gamex86.dll manually using Winzip or similar or install Doom 3 in a different directory.</li>
<li>You have a '''firewall''' installed that prevents the copy procedure, because since version 1.03, TDM has a built-in mission downloader. This misbehavior has been reported for the '''COMODO Firewall'''.</li>
</ul>
<li>It is also possible that an '''old version of gamex86.dll''' (or gamex86.so) is lying around in your Doom 3 folder. Delete it and try again.</li>
</ul>

=== Textures are missing, screen mostly black ===

[[Image:Tdm missing textures.jpg|right|240px|Black textures]]

Look into your '''darkmod.cfg''' inside your <tt>darkmod</tt> folder and check that the following settings are like shown below:

<pre style="max-width:35em">
seta image_usePrecompressedTextures "1"
seta image_useNormalCompression "2"
seta image_useAllFormats "1"
seta image_useCompression "0"
seta image_preload "1"
</pre>

=== Textures are missing, shadows are pitch black ===

Try disabling the AGP surface accelerator in DXDIAG.

=== Graphic Corruption ===

One report we had was for a Radeon ATI HD 4650, catalyst 10.9. This screen corruption as I understand it was heavy pixelation even on the menus. Closing down Xfire fixed it. "I fiddled with the xfire Doom 3 configuration through the xfire_games.ini, and determined it has to do with InGameFlags portion. For some reason the settings in that were interfering with doom 3, and after I removed some things from there, I was still able to run xfire, and doom 3 was still able to look proper."

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== The briefing is very fuzzy ===

Look into your '''DoomConfig.cfg''' inside your <tt>darkmod</tt> folder and check that the following settings are like shown below:

seta image_roundDown "1"
seta image_forceDownSize "0"
seta image_downSize "0"

=== The sky is corrupted ===

You either see black sky, or fragments of other textures. This seems only to happen on Geforce 6800 cards.

There are two fixes for this:

As a quick fix you can rename the following folder:

env/skyboxes/skybox_darkland_ne

to a different name. That will result in black sky.

Alternatively, edit the file <tt>materials/tdm_sky.mtr</tt> with '''Wordpad''' or a different editor and
find the sky material named '''textures/darkmod/nature/skybox/skybox_darkland_NE''':

<pre>
//Author: Dram
//skybox_ocean with ocean replaced with dark land
//Moon moved to north east by Fidcal
textures/darkmod/nature/skybox/skybox_darkland_NE
{
qer_editorimage env/skyboxes/skybox_ocean/ocean_ed
noFragment
noshadows
noimpact
nooverlays
forceOpaque
{
forceHighQuality
blend add
cameraCubeMap env/skyboxes/skybox_darkland_ne/darkland_NE
texgen skybox
texgen wobblesky .0 .0 .0
}
}
</pre>

In this declaration, comment out the line that reads '''forceHighQuality''' by adding <tt>//</tt> in front of it:

// forceHighQuality

That should fix the sky and make it render correctly.

=== The Sky rotates ===

This problem only affects FMs with a dynamic sky (eg, moving clouds etc.).

If you see the sky spinning it may be an ATI graphics card problem. One report says this was cured by turning off Catalyst AI. Also gives better loading times and cures [[#HDR-Lite Post-Processing problems|HDR-Lite Post-Processing Problems]].

If that doesn't fix it then try this. Note that it replaces dynamic sky with a static clear one so it might look odd in a stormy FM for example, but better than a spinning sky:

<pre>

* Create a new folder in your darkmod folder called materials.
* Within it create a plain text file named no_skybox.mtr.
* Paste in the following:

textures/smf/portal_sky
{
qer_editorimage env/skyboxes/skybox_ocean/ocean_ed
noFragment

noimpact
nooverlays
forceOpaque
noShadows
{
forceHighQuality
blend add
cameraCubeMap env/skyboxes/skybox_darkland_ne/darkland_NE
texgen skybox
texgen wobblesky .0 .0 .0
}
}

</pre>

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== HDR-Lite Post-Processing problems ===

Some owners of ATI graphics cards reported various artifacts when HDR-Lite Post-Processing was enabled. Among these artifacts are a distorted or upside-down screen and spinning sky. These can usually be fixed by disabling Catalyst AI, which also gives better loading times.

To turn off Catalyst AI, open your Catalyst control panel, go to 'graphics' at the top left, select '3d' from the dropdown list and on the new menu below, select 'AI'. Now select the 'Disable Catalyst A.I.' checkbox.

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

It has also been suspected that HDR-Lite Post-Processing may lead to [[#Underwater performance poor|poor performance underwater]], see next point:

===Underwater performance poor===

Some people suffer from very low framerates underwater with HDR-Lite Post-Processing enabled. Currently, the only known fix to this problem is to set '''g_doubleVision''' to 0 in the console. This however disables the doubleVision effect completely, so that there is no underwater-blur any more. The murkiness still remains though.

===Upside-down screen===

If you get an upside-down screen, you can either turn off Catalyst AI if you have an ATI card or try turning off HDR-Lite Post-Processing in the advanced video options.

To turn off Catalyst AI, open your Catalyst control panel, go to 'graphics' at the top left, select '3d' from the dropdown list and on the new menu below, select 'AI'. Now select the 'Disable Catalyst A.I.' checkbox.

(For more recent Catalyst versions see: [[#Disable Catalyst AI in recent AMD ATI drivers|Disable Catalyst AI in recent AMD ATI drivers]] )

=== The game is '''very''' slow! ===

If you get less than 10 FPS, or the game even stutters, please try this:

Look into your '''DoomConfig.cfg''' inside your <tt>darkmod</tt> folder and check that the
following settings are like shown below:

<pre style="max-width:35em">
seta image_usePrecompressedTextures "1"
seta image_useNormalCompression "2"
seta image_useAllFormats "1"
seta image_useCompression "1"
seta image_preload "1"
</pre>

If that doesn't help, your system might run out of memory. Either upgrade to more than 1 Gbyte memory,
or try to close other applications before playing.

Please see also the article about [[Performance Tweaks]] to improve the performance.

=== Slow loading times ===

If you find an FM is very slow to load it may be an ATI graphics card problem. One report says this was cured by turning off Catalyst AI. Also cures [[#HDR-Lite Post-Processing problems|HDR-Lite Post-Processing Problems]].

Changing the following settings to 0 will also reduce loading time, but be warned: if you have a lower-end system, poor graphics card, or low ram, you will likely notice a performance hit ingame since you will now be using uncompressed textures.
<pre style="max-width:35em">
seta image_useNormalCompression "0"
seta image_useCompression "0"
</pre>

===Game freezes for several seconds when opening doors===
The following problems :

A) "game freezes and loads some data from hard drive while opening doors"
B) "while loading mission you are returned to the menu and need to restart loading"

are often resolved by disabling EAX 4.0 HD in the Audio Settings menu.

===Game exits to menu after mission load, with renderpipe error in console===

* {{Red|Version 1.06 does not use named pipes. This is a depreciated issue.}}

'''Symptoms:''' Missions are installed properly and will load, but after they reach 100% you are returned to the main menu or objectives screen. If you open the console (Ctrl-Alt-~ on US keyboards), you see one/both of these errors:

ERROR: Failed to open \\.\pipe\dm_renderpipe

or

ERROR: idRenderSystemLocal::uncrop currentcrop <1

'''Solution:''' Some firewalls, notably ''Sunbelt Firewall'' (aka ''Kerio Firewall'') are known to interfere with TDM's lightgem, ''even when "disabled"''. To fix this problem, completely uninstall the firewall and get a different one instead.

Related [http://bugs.angua.at/view.php?id=543 #543]: Consider using glReadPixels for lightgem instead of named pipes.

==="COULD NOT FIND TDMLAUNCHER" when installing an FM===

If you receive this error message you should check the start-arguments of DOOM3.exe / tdmlauncher.exe. Arguments are stored in darkmod/dmargs.txt and a faulty syntax e.g. a missing "+" before a "set"-command, will lead to this error message. Steam users are advised to remove any launch-options from Doom.

===The sound lags behind the picture===

This seems to happen on some Linux Distributions with PulseAudio. Doom's sound engine defaults to ALSA, you can try to use OSS instead:

Add the following to your ''dmargs.txt'' (it is in ''~/.doom/darkmod/''):

+set s_driver oss

If your system does not provide OSS or a working OSS-emulation (try ''padsp ./tmdlauncher-linux''), reset this to ''best'' which means ALSA.

While OSS or ALSA deal directly with the sound hardware, PulseAudio is a soundserver that puts itself between the application (doom3) and ALSA. Your goal is to bypass the PA-part while playing TDM.

You can either disable the PulseAudio daemon temporarily or connect Doom directly to ALSA.

To disable PA, create a file named ''client.conf'' in ''~/.pulse'' which contains:

autospawn=no

Then open a terminal and type:

pulseaudio -k

When sound playback fails, make sure you have ''s_driver'' set to ''best'', and ''s_alsa_pcm'' to ''default''. When it works, you propably want to adjust volume settings outside TDM. Try ''alsamixer'' (in a terminal).

When you're finished playing, turn PA back on:

pulseaudio -D

starts the daemon. Changing ''autospawn'' to ''yes'' should prevent you from doing this manually after every reboot. :)

The other way, just bypassing PA, requires some knowledge about your sound hardware. Type

aplay -L

This gives you a long list of your ALSA playback devices, three lines for each, first line is ''<name>''. Choose the one with PCM Playback that your speakers are connected to and add

+set s_alsa_pcm <name>

to ''dmargs.txt''. If ''<name>'' is not convenient for you just try something like hw:1,0 if you know what you are doing, but be aware abstract designations like ''default'' will get "hijacked" by PA.

=== Changing the screen resolution/aspect ratio does nothing!? ===

These changes require a restart of Doom to work. Alternatively the command vid_restart can be issued at the console. It can take quite some time to execute this command, depending on whether or not you're already ingame. It will still be a lot faster than restarting and reloading the game though.

=== Disable Catalyst AI in recent AMD ATI drivers ===

From (at least) Catalyst versions 10.12 and beyond, the ability to disable Catalyst AI properly
has been changed or removed.

----

Rage3d and Guru3d have advised using "Radeon Pro" to address this.

Steps

* 1) Remove Catalyst Control Center (removing all ATI drivers recommended then re-install just the Display driver)
* 2) Download and install "Radeon Pro" [http://forums.guru3d.com/showthread.php?t=322031 Radeon Pro Thread at Guru3D]
* 3) Create a profile as follows:

<pre>
If you're using RadeonPro, create a profile for the game you want to disable Catalyst AI.
Right-click the newly created profile, keep left shift key pressed and choose
Open Location on context-menu, this will open the profile's XML definition.
Append a new line and add entry like this

<Property name="CatalystAI" value="0" />

Save the file and start the game. CatalystAI should be disabled.

I also recommend to open ___GlobalProfile.xml
(found on same directory where your profile is saved)
and look for "CatalystAI" entry, it must be equal to "1"
otherwise CatalystAI will be kept disabled after you exit your game.

CFX disabled by setting CatalystAI to 0
</pre>

Here's another alternate method for Windows users:

* 1) Obtain a copy of the free "ATI Tray Tools" by Ray Adams from [http://downloads.guru3d.com/download.php?det=733 Guru3d].

* 2) Install it into your Windows tray.

* 3) Right-click it.

* 4) Select Direct 3d -> Catalyst AI -> Off.

=== Disable Nvidia "Threaded Optimizations" ===

Many random crash behaviors seen by Nvidia users can be resolve by the following steps:

<pre>

Open Nvidia Control Panel ->

Manage 3D Settings ->

Bottom half of list locate "Threaded Optimization" <-- Set to NO / Off

Also set "Multi-display/Mixed GPU acceleration" to "Single display performance mode"

</pre>

=== Getting "Malloc Failure for #######" crash-to-desktop ===

Because Doom 3 is a 32-bit game, it can only utilize a certain amount of RAM. When Doom 3 needs more memory, but cannot allocate anymore, it crashes with an error saying something like
<pre>
Shutdown event system
--------------------------------------
malloc failure for 3145781
</pre>

If you run into malloc failures, it is suggested to try the following:

1) Edit your darkmod.cfg and use the following:
seta image_downSizeBump "1"
seta image_downSizeBumpLimit "256"

These will reduce the bumpmap size. Memory impact will be few hundred megabytes lower, at the expensee of very minor blurring of texture quality.

2) If the above does not help you it is recommended you try
seta image_downSize "1"
seta com_videoRam "512" (or however much video RAM you have).

These will reduce all texture sizes. Memory impact will be much lower, but the graphics are visually pixelated, depending on the com_videoRam number. But at least the mission will be more likely run with systems with low RAM.

A possible solution is to patch Doom3.exe with a [http://www.ntcore.com/4gb_patch.php 4GB Patcher] to allow the game to allocate more memory, but the TheDarkMod.exe should already be using large memory space.

=== Screen is Oversized in Fullscreen Mode (Image is too large to fit the screen area available) ===
Windows 7 Aero desktop is known to make the screen too large in fullscreen mode. This can be remedied by setting Windows 7 Aero to Basic.

This issue is discussed in more detail [http://forums.thedarkmod.com/topic/14622-oversized-title-screen-solved-caused-by-aero/ HERE].

== See also ==

* [[Known Bugs]]
* [[Gameplay]]

{{installation}} {{general}}

Tdm update

2015-02-10T06:55:56Z

Demagogue: /* Use it to install TDM */

'''tdm_update''' is the primary method to install and update The Dark Mod.

== Where to get it ==

Each of our mirrors contains a copy of the updater. Get it from here:

* Download from www.fical.com: [http://www.fidcal.com/darkuser/tdm_update_win.zip Windows] or [http://www.fidcal.com/darkuser/tdm_update_linux.zip Linux] or [http://www.fidcal.com/darkuser/tdm_update_macosx.zip Mac OSX]
* Download from www.southquarter.com: [http://www.southquarter.com/tdm/tdm_update_win.zip Windows] or [http://www.southquarter.com/tdm/tdm_update_linux.zip Linux] or [http://www.southquarter.com/tdm/tdm_update_macosx.zip Mac OSX]
* Download from darkmod.taaaki.za.net: [http://darkmod.taaaki.za.net/release/tdm_update_win.zip Windows] or [http://darkmod.taaaki.za.net/release/tdm_update_linux.zip Linux] or [http://darkmod.taaaki.za.net/release/tdm_update_macosx.zip Mac OSX]

== Use it to '''install''' TDM ==

Unzip the downloaded archive and place the tdm_update file into any folder named "Darkmod" or "darkmod".

For versions before 2.0 standalone place:

* Windows: tdm_update.exe into '''C:\Games\Doom3\darkmod''' (or wherever Doom 3 is installed) and run it
* Linux: tdm_update.linux into '''~/.doom3/darkmod''' and run it
* Mac: tdm_update.macosx into '''~/Library/Application Support/Doom 3/darkmod''' and run it from the console. (Note: there is a custom darkmod.zip file available containing a helper script allowing you do run the updater directly from Finder - see the Mac OSX section in the [[Installation#Install_on_Mac_OSX Installation]] article.)

Note: You must either create the "darkmod" folder by yourself, or place the program directly into the Doom 3 folder so it can create the folder for you.

== Use it to '''update''' TDM ==

Simple navigate to your darkmod folder and run tdm_update.

== Troubleshooting ==

=== Windows 2000 ===
Please install the GDI+ redistributable package, as described in this article: [[TDM in Windows 2000]]

=== Updater closes almost as soon as it's started (1.00 to 1.02 only) ===

Clear out your temp folder, as follows:

# Click Start
# Click Run
# Type <tt>%temp%</tt> and press enter (make sure you include the % signs) (if this step doesn't work, try navigating to it - see below for the path)
# Select all ({{key|CTRL}}-{{key|A}}) and ({{key|DEL}}) them.

On Windows Vista, the temporary folder in question is usually at <tt>C:\Users\[your Windows user name]\AppData\Local\Temp</tt>. On Windows XP, look in <tt>C:\Documents and Settings\[your Windows user name]\Application Data\Local Settings\Temp</tt>.

=== Updater crashes as soon as it attempts to delete or modify files as part of the update ===

This can happen (in Windows) if the folder is set to "read only" in the folder properties. It is fixed by right clicking on the top folder, clicking properties, and unchecking the box for "read only".

=== I am behind a proxy ===

Open a console window, navigate (chdir) to your Darkmod folder and use the --proxy argument.

In Windows, open the "Advanced Options" dialog right after starting the updater, and enter the proxy information in the entry field.

== See also ==

* [[FAQ]] - Frequently Answered Questions
* [[:Category:What%27s_New]] - What's new in each release

Tdm update

2015-02-10T06:55:32Z

Demagogue: /* Use it to install TDM */

'''tdm_update''' is the primary method to install and update The Dark Mod.

== Where to get it ==

Each of our mirrors contains a copy of the updater. Get it from here:

* Download from www.fical.com: [http://www.fidcal.com/darkuser/tdm_update_win.zip Windows] or [http://www.fidcal.com/darkuser/tdm_update_linux.zip Linux] or [http://www.fidcal.com/darkuser/tdm_update_macosx.zip Mac OSX]
* Download from www.southquarter.com: [http://www.southquarter.com/tdm/tdm_update_win.zip Windows] or [http://www.southquarter.com/tdm/tdm_update_linux.zip Linux] or [http://www.southquarter.com/tdm/tdm_update_macosx.zip Mac OSX]
* Download from darkmod.taaaki.za.net: [http://darkmod.taaaki.za.net/release/tdm_update_win.zip Windows] or [http://darkmod.taaaki.za.net/release/tdm_update_linux.zip Linux] or [http://darkmod.taaaki.za.net/release/tdm_update_macosx.zip Mac OSX]

== Use it to '''install''' TDM ==

Unzip the downloaded archive and place tdm_update.exe into any folder named "Darkmod" or "darkmod".

For versions before 2.0 standalone place:

* Windows: tdm_update.exe into '''C:\Games\Doom3\darkmod''' (or wherever Doom 3 is installed) and run it
* Linux: tdm_update.linux into '''~/.doom3/darkmod''' and run it
* Mac: tdm_update.macosx into '''~/Library/Application Support/Doom 3/darkmod''' and run it from the console. (Note: there is a custom darkmod.zip file available containing a helper script allowing you do run the updater directly from Finder - see the Mac OSX section in the [[Installation#Install_on_Mac_OSX Installation]] article.)

Note: You must either create the "darkmod" folder by yourself, or place the program directly into the Doom 3 folder so it can create the folder for you.

== Use it to '''update''' TDM ==

Simple navigate to your darkmod folder and run tdm_update.

== Troubleshooting ==

=== Windows 2000 ===
Please install the GDI+ redistributable package, as described in this article: [[TDM in Windows 2000]]

=== Updater closes almost as soon as it's started (1.00 to 1.02 only) ===

Clear out your temp folder, as follows:

# Click Start
# Click Run
# Type <tt>%temp%</tt> and press enter (make sure you include the % signs) (if this step doesn't work, try navigating to it - see below for the path)
# Select all ({{key|CTRL}}-{{key|A}}) and ({{key|DEL}}) them.

On Windows Vista, the temporary folder in question is usually at <tt>C:\Users\[your Windows user name]\AppData\Local\Temp</tt>. On Windows XP, look in <tt>C:\Documents and Settings\[your Windows user name]\Application Data\Local Settings\Temp</tt>.

=== Updater crashes as soon as it attempts to delete or modify files as part of the update ===

This can happen (in Windows) if the folder is set to "read only" in the folder properties. It is fixed by right clicking on the top folder, clicking properties, and unchecking the box for "read only".

=== I am behind a proxy ===

Open a console window, navigate (chdir) to your Darkmod folder and use the --proxy argument.

In Windows, open the "Advanced Options" dialog right after starting the updater, and enter the proxy information in the entry field.

== See also ==

* [[FAQ]] - Frequently Answered Questions
* [[:Category:What%27s_New]] - What's new in each release

Tdm update

2015-02-10T06:54:37Z

Demagogue: /* Use it to install TDM */

'''tdm_update''' is the primary method to install and update The Dark Mod.

== Where to get it ==

Each of our mirrors contains a copy of the updater. Get it from here:

* Download from www.fical.com: [http://www.fidcal.com/darkuser/tdm_update_win.zip Windows] or [http://www.fidcal.com/darkuser/tdm_update_linux.zip Linux] or [http://www.fidcal.com/darkuser/tdm_update_macosx.zip Mac OSX]
* Download from www.southquarter.com: [http://www.southquarter.com/tdm/tdm_update_win.zip Windows] or [http://www.southquarter.com/tdm/tdm_update_linux.zip Linux] or [http://www.southquarter.com/tdm/tdm_update_macosx.zip Mac OSX]
* Download from darkmod.taaaki.za.net: [http://darkmod.taaaki.za.net/release/tdm_update_win.zip Windows] or [http://darkmod.taaaki.za.net/release/tdm_update_linux.zip Linux] or [http://darkmod.taaaki.za.net/release/tdm_update_macosx.zip Mac OSX]

== Use it to '''install''' TDM ==

Unzip the downloaded archive and place it in any folder named "Darkmod" or "darkmod".

For versions before 2.0 standalone, place it:

* Windows: tdm_update.exe into '''C:\Games\Doom3\darkmod''' (or wherever Doom 3 is installed) and run it
* Linux: tdm_update.linux into '''~/.doom3/darkmod''' and run it
* Mac: tdm_update.macosx into '''~/Library/Application Support/Doom 3/darkmod''' and run it from the console. (Note: there is a custom darkmod.zip file available containing a helper script allowing you do run the updater directly from Finder - see the Mac OSX section in the [[Installation#Install_on_Mac_OSX Installation]] article.)

Note: You must either create the "darkmod" folder by yourself, or place the program directly into the Doom 3 folder so it can create the folder for you.

== Use it to '''update''' TDM ==

Simple navigate to your darkmod folder and run tdm_update.

== Troubleshooting ==

=== Windows 2000 ===
Please install the GDI+ redistributable package, as described in this article: [[TDM in Windows 2000]]

=== Updater closes almost as soon as it's started (1.00 to 1.02 only) ===

Clear out your temp folder, as follows:

# Click Start
# Click Run
# Type <tt>%temp%</tt> and press enter (make sure you include the % signs) (if this step doesn't work, try navigating to it - see below for the path)
# Select all ({{key|CTRL}}-{{key|A}}) and ({{key|DEL}}) them.

On Windows Vista, the temporary folder in question is usually at <tt>C:\Users\[your Windows user name]\AppData\Local\Temp</tt>. On Windows XP, look in <tt>C:\Documents and Settings\[your Windows user name]\Application Data\Local Settings\Temp</tt>.

=== Updater crashes as soon as it attempts to delete or modify files as part of the update ===

This can happen (in Windows) if the folder is set to "read only" in the folder properties. It is fixed by right clicking on the top folder, clicking properties, and unchecking the box for "read only".

=== I am behind a proxy ===

Open a console window, navigate (chdir) to your Darkmod folder and use the --proxy argument.

In Windows, open the "Advanced Options" dialog right after starting the updater, and enter the proxy information in the entry field.

== See also ==

* [[FAQ]] - Frequently Answered Questions
* [[:Category:What%27s_New]] - What's new in each release

Tdm update

2015-02-10T06:50:49Z

Demagogue: /* Updater crashes as soon as it attempts to add downloaded files in the folder */

'''tdm_update''' is the primary method to install and update The Dark Mod.

== Where to get it ==

Each of our mirrors contains a copy of the updater. Get it from here:

* Download from www.fical.com: [http://www.fidcal.com/darkuser/tdm_update_win.zip Windows] or [http://www.fidcal.com/darkuser/tdm_update_linux.zip Linux] or [http://www.fidcal.com/darkuser/tdm_update_macosx.zip Mac OSX]
* Download from www.southquarter.com: [http://www.southquarter.com/tdm/tdm_update_win.zip Windows] or [http://www.southquarter.com/tdm/tdm_update_linux.zip Linux] or [http://www.southquarter.com/tdm/tdm_update_macosx.zip Mac OSX]
* Download from darkmod.taaaki.za.net: [http://darkmod.taaaki.za.net/release/tdm_update_win.zip Windows] or [http://darkmod.taaaki.za.net/release/tdm_update_linux.zip Linux] or [http://darkmod.taaaki.za.net/release/tdm_update_macosx.zip Mac OSX]

== Use it to '''install''' TDM ==

Unzip the downloaded archive and place:

* Windows: tdm_update.exe into '''C:\Games\Doom3\darkmod''' (or wherever Doom 3 is installed) and run it
* Linux: tdm_update.linux into '''~/.doom3/darkmod''' and run it
* Mac: tdm_update.macosx into '''~/Library/Application Support/Doom 3/darkmod''' and run it from the console. (Note: there is a custom darkmod.zip file available containing a helper script allowing you do run the updater directly from Finder - see the Mac OSX section in the [[Installation#Install_on_Mac_OSX Installation]] article.)

Note: You must either create the "darkmod" folder by yourself, or place the program directly into the Doom 3 folder so it can create the folder for you.

== Use it to '''update''' TDM ==

Simple navigate to your darkmod folder and run tdm_update.

== Troubleshooting ==

=== Windows 2000 ===
Please install the GDI+ redistributable package, as described in this article: [[TDM in Windows 2000]]

=== Updater closes almost as soon as it's started (1.00 to 1.02 only) ===

Clear out your temp folder, as follows:

# Click Start
# Click Run
# Type <tt>%temp%</tt> and press enter (make sure you include the % signs) (if this step doesn't work, try navigating to it - see below for the path)
# Select all ({{key|CTRL}}-{{key|A}}) and ({{key|DEL}}) them.

On Windows Vista, the temporary folder in question is usually at <tt>C:\Users\[your Windows user name]\AppData\Local\Temp</tt>. On Windows XP, look in <tt>C:\Documents and Settings\[your Windows user name]\Application Data\Local Settings\Temp</tt>.

=== Updater crashes as soon as it attempts to delete or modify files as part of the update ===

This can happen (in Windows) if the folder is set to "read only" in the folder properties. It is fixed by right clicking on the top folder, clicking properties, and unchecking the box for "read only".

=== I am behind a proxy ===

Open a console window, navigate (chdir) to your Darkmod folder and use the --proxy argument.

In Windows, open the "Advanced Options" dialog right after starting the updater, and enter the proxy information in the entry field.

== See also ==

* [[FAQ]] - Frequently Answered Questions
* [[:Category:What%27s_New]] - What's new in each release

Tdm update

2015-02-10T06:50:11Z

Demagogue: /* Troubleshooting */

'''tdm_update''' is the primary method to install and update The Dark Mod.

== Where to get it ==

Each of our mirrors contains a copy of the updater. Get it from here:

* Download from www.fical.com: [http://www.fidcal.com/darkuser/tdm_update_win.zip Windows] or [http://www.fidcal.com/darkuser/tdm_update_linux.zip Linux] or [http://www.fidcal.com/darkuser/tdm_update_macosx.zip Mac OSX]
* Download from www.southquarter.com: [http://www.southquarter.com/tdm/tdm_update_win.zip Windows] or [http://www.southquarter.com/tdm/tdm_update_linux.zip Linux] or [http://www.southquarter.com/tdm/tdm_update_macosx.zip Mac OSX]
* Download from darkmod.taaaki.za.net: [http://darkmod.taaaki.za.net/release/tdm_update_win.zip Windows] or [http://darkmod.taaaki.za.net/release/tdm_update_linux.zip Linux] or [http://darkmod.taaaki.za.net/release/tdm_update_macosx.zip Mac OSX]

== Use it to '''install''' TDM ==

Unzip the downloaded archive and place:

* Windows: tdm_update.exe into '''C:\Games\Doom3\darkmod''' (or wherever Doom 3 is installed) and run it
* Linux: tdm_update.linux into '''~/.doom3/darkmod''' and run it
* Mac: tdm_update.macosx into '''~/Library/Application Support/Doom 3/darkmod''' and run it from the console. (Note: there is a custom darkmod.zip file available containing a helper script allowing you do run the updater directly from Finder - see the Mac OSX section in the [[Installation#Install_on_Mac_OSX Installation]] article.)

Note: You must either create the "darkmod" folder by yourself, or place the program directly into the Doom 3 folder so it can create the folder for you.

== Use it to '''update''' TDM ==

Simple navigate to your darkmod folder and run tdm_update.

== Troubleshooting ==

=== Windows 2000 ===
Please install the GDI+ redistributable package, as described in this article: [[TDM in Windows 2000]]

=== Updater closes almost as soon as it's started (1.00 to 1.02 only) ===

Clear out your temp folder, as follows:

# Click Start
# Click Run
# Type <tt>%temp%</tt> and press enter (make sure you include the % signs) (if this step doesn't work, try navigating to it - see below for the path)
# Select all ({{key|CTRL}}-{{key|A}}) and ({{key|DEL}}) them.

On Windows Vista, the temporary folder in question is usually at <tt>C:\Users\[your Windows user name]\AppData\Local\Temp</tt>. On Windows XP, look in <tt>C:\Documents and Settings\[your Windows user name]\Application Data\Local Settings\Temp</tt>.

=== Updater crashes as soon as it attempts to add downloaded files in the folder ===

This can happen (in Windows) if the folder is set to "read only" in the folder properties. It is fixed by right clicking on the top folder, clicking properties, and unchecking the box for "read only".

=== I am behind a proxy ===

Open a console window, navigate (chdir) to your Darkmod folder and use the --proxy argument.

In Windows, open the "Advanced Options" dialog right after starting the updater, and enter the proxy information in the entry field.

== See also ==

* [[FAQ]] - Frequently Answered Questions
* [[:Category:What%27s_New]] - What's new in each release

Add-ons

2015-01-14T01:41:40Z

Demagogue: /* See also */

The Dark Mod itself is a mod for the game Doom 3, but it is also possible to mod the mod by installing '''add-ons'''. A few of thes exist already, and they enhance the gameplay or the visuals:

== List of Add-ons ==

{|class="wikitable sortable" border=1 style="border-collapse: collapse; font-size:90%" cellspacing=0 cellpadding=3 width=100%

|-
!bgcolor=#d0d0e0 width="12%"|Name
!bgcolor=#d0d0e0 width="7%"|Author(s)
!bgcolor=#d0d0e0 width="5%" class="unsortable"|Links
!bgcolor=#d0d0e0 width="7%"|Release
!bgcolor=#d0d0e0 width="7%"|Last update
!bgcolor=#d0d0e0 width="5%" class="unsortable"|Size (MB)
!bgcolor=#d0d0e0|Changes
|-



|-
!align=left|Upright Bow Aimer
|Dram
|{{Bloodgate-Addon|MOD_UprightBowAimer.pk4}} {{Forumlink|http://modetwo.net/darkmod/index.php?/topic/12271-mod-upright-bow-with-aimer/}}
|2011-02-06
|2011-02-06
|0.3
|'''Visuals:''' The bow aimer '''Gameplay: None'''
|-

|-
!align=left|Black Light
|Tels
|{{Bloodgate-Addon|tels_tdm_black_light.pk4}} {{Forumlink|http://modetwo.net/darkmod/index.php?/topic/12336-add-on-black-light-aka-pimp-my-visuals/}}
|2011-02-04
|2011-07-24
|0.01
|'''Visuals:''' Enhanced fire and torch particles, adds arrow glow and trails, prettier explosions etc. '''Gameplay: None'''
|-

|}

== See also ==

* [http://www.bloodgate.com/mirrors/tdm/pub/add-ons/ Mirror at Bloodgate.com]
* [[Fan_Created_Modifications]]

[[Category:Fan_Missions]]

Fan Created Modifications

2015-01-14T01:40:29Z

Demagogue: /* See Also */

== Links to Fan Made Contributions ==

This page is to collect any unofficial modifications or tweaks or instructions created by fans that modify the game in some respect. These modifications are not supported by the team nor even necessarily recommended. If you have a question about any of them, then ask in the forums. Please notify a team member if a link becomes broken.

* Instructions for deleting a type of AI from all FMs, like a spider or zombie: See this post [http://forums.thedarkmod.com/topic/16855-arachnophobia-vs-tdm-missions-with-giant-spiders/?p=363347] and the four posts following it.

== See Also ==

[[Add-ons]]

{{tutorial-editing}}

Fan Created Modifications

2015-01-14T01:40:16Z

Demagogue: /* Links to Fan Made Contributions */

Fan Created Modifications

2015-01-13T11:07:59Z

Demagogue: /* Links to Fan Made Contributions */

Fan Created Modifications

2015-01-13T11:04:21Z

Demagogue: /* Links to Fan Made Contributions */

Fan Created Modifications

2015-01-13T11:00:12Z

Demagogue: Created page with "== Links to Fan Made Contributions == (Please notify a team member if a link becomes broken.) * Instructions for deleting a type of AI from all FMs, like a spider or zombie..."

== Links to Fan Made Contributions ==

(Please notify a team member if a link becomes broken.)

* Instructions for deleting a type of AI from all FMs, like a spider or zombie: See this post [http://forums.thedarkmod.com/topic/16855-arachnophobia-vs-tdm-missions-with-giant-spiders/?p=363347] and the four posts following it.

Editing FAQ - Troubleshooting & How-To

2014-08-08T03:26:04Z

Demagogue: /* Scripting */

Below are some common issues and questions mappers have had in the Editor's Guild forum with common solutions. Some of this assumes you've already gone through the [[A_-_Z_Beginner_Full_Guide_Start_Here!]], [[Startpack_Mappers'_Guide]], and [[Dark_Radiant_Must_Know_Basic_Intro]]. (If you know a FAQ not here and worth going in this list, and you know the right answer(!), or you can improve an existing answer, please add it if you have edit control or PM it to a team-member if you don't.)

= Troubleshooting FAQ =

== Rendering & VisPortal Issues ==

'''Q. Some of my brushes have disappeared or turned black and won't render.'''

'''A.''' This can happen when two touching brushes around the seam are not perfectly flush with one another and the rendering hiccups for those brushes & brushes behind it, either there's a tiny wedge or overlap or gap or weird angle between them. The usual solution is to make sure the brushes are snapped to the grid and perfectly flush against one another, or more generally to simplify the brushwork around the seam of the disappearing brushes.

'''Q. My visportal is not showing up or not closing like it should (you can check this with by typing "r_showportals 1" in the console. The portal edge will show green when open and red when closed.).'''

'''A.''' A common reason for that is that the two areas separated by the portal are not hermetically sealed and there's an internal leak, either (1) there may be an unportaled gap between the two, possibly covered up by func_static (which do not seal) or possibly caused by an inadvertent hole created by the first FAQ question above, or (2) an internal leak can happen when all sides of the visportal are not buried in or flush against sealing brushes, and there's a gap between the visportal and brush, or possibly even a tiny gap just touching the visportal side is enough to break it. A way to check if there's an internal leak, and locating it if there is, is described here: [[Visportals#Trouble-shooting]]. Other reasons it might fail are also described there (such as accidentally changing a nodraw texture to something else).

'''Q. I can see other rooms behind a mirror (or any reflective surface) through it, instead of just a reflection.'''

'''A.''' The area behind a mirror should be in a separate leaf (visportaled area) behind a closed visportal so it doesn't render. This problem usually means the two areas aren't in separate leafs, the portal isn't closed, or there's an internal leak between the areas in front of and behind the mirror.

'''Q. Help! I'm having rendering & visPortal issues all over the place ... broken portals, sparkly lines, disappearing brushes, z-fighting, uneven walls, etc.'''

'''A.''' As a general piece of advice, messy brushwork leads to trouble one way or another. To keep your brushwork clean:
* keep snapped to the grid (Ctrl+G toggles) & stay away from small grid levels (Typing a number or Plus/Minus changes the grid scale; 8 is a good starting grid; staying at or above 2 or 4 is fine for most stuff; going below 1 is usually just for special situations).
* Make brush intersections perfectly flush.
* Stay away from unnecessary tiny brushes & wedges (leave detail work to func_statics; brushes are for closing off leafs and the void. Of course you can do fine detail work with brushes & convert them to a func_static).
* Don't use the "CGS Subtract" tool if it will shatter the brush into tiny slivers; use the cut tool instead (open by pushing "X").
* You can use patches for uneven geometry with square brushes underneath textured with caulk.
* When rotating geometry, avoid weird angles when you can (where vertexes end up off the grid), and for multi-brush structures, build the whole thing first *then* rotate it all together instead of rotating & placing each brush individually.
These aren't rules set in concrete if you want to do something special once in a while, but general rules of thumb that will make life a lot easier if you generally stick to them.

== Crashes and Warnings ==

'''Q. My map has a leak in it, but a pointfile either isn't generated or doesn't make sense. (A pointfile is generated when dmap occurs and there's a leak, then you open DarkRadient and click File>Pointfile to see it. It normally runs a red line that ends in the void, pointing out the leak).'''

'''A.''' Make sure a gap isn't covered up with func_statics. If the origin of a model is in the void it will also cause a leak with a non-sense pointfile. Read more on the [[Leaking maps]] page.

'''Q. How do I scroll up through the console output to see what a problem was during dmap or map or in-game?'''

'''A.''' Use the mouse wheel or PageUp/Down to scroll through the console.

'''Q. I'm getting an error message "warning: aas is out of date" once my map has loaded. What does it mean and what do I do?'''

'''A.''' The AAS is for AI pathfinding. It usually means you changed brushwork and started a map without dmapping first. The solution is to dmap. If you dmap and still get the warning, delete your .aasxx, .proc, and .cm files in the maps folder and dmap again. If you're still getting a warning, then it could be a sign that something in your map is breaking the AAS pathfinding. Try monsterclipping tricky areas for the AI to path (like around objects and uneven ground) or clean up messy brushwork that might break the dmapping like sliver brushes.

'''Q. I have encountered a malloc failure error while dmapping my level. Instead of finishing with the dmap operation, it crashes midway with an error message.'''

'''A1.''' One solution to this is given in the Dmap wiki entry here: [[Dmap#Malloc_Errors]].

'''A2.''' This is what I've done to fix this exact issue. Open the map in DarkRadiant, select everything, copy to clipboard. Open another instance of DarkRadiant and paste from clipboard. Save as new filename and dmap new file and that has worked 3 times now with random unresolvable crashes.

'''A3.''' GC and I have found correlations between visportalling and mAlloc errors. Time to re-arrange your visportals. In NHAT, we had many malloc problems until we retooled how each area was portaled. Originally, every other visleaf had tons of entities, while half had hardly any. That's not neccessarily bad, but it strains the dmapper when one or two visleafs are cluttered with entities that really bloat your mapname.proc file. We added a few more portals to even out entity distribution, and dmap was happy again.

== Performance Issues ==

'''Q. My map is so slow. How do I improve performance?'''

'''A.''' See these wiki entry: [[Performance:_Essential_Must-Knows]]. Tips include:
* Reduce AI [[Pathfinding]] with Monsterclipping helps performance, simplifying complex bumpy surfaces into 1 smooth monsterclipped surface (or raise the monsterclip height to be inside the ceiling and there is no pathfinding computation at all), or excluding entire surfaces AI should never walk on, like detail brushwork or some roofs.
* Use [[Interleaved_Thinking_optimization]]. Reducing AI think-time helps performance quite a bit.
* break-up long lines of sight,
* improve visportal & leaf placement (so less architecture is rendered at a time),
* use fewer AI,
* convert ornamental brushwork into func_static,
* reduce the overlap of light sources on surfaces by adjusting their placement & reducing their light-radius. (Every time a new light hits a surface, it's another render pass. So 4 lights hitting a surface processes it 4 times. If only 1 light hit it, its lighting is processed in 1/4 the time), and
* set objects and lights to "noshadow" if it won't be noticable to the player or affect gameplay (possibly in combination with low-poly shadow meshes or shadowy decals. Note that "noshadow" has two jobs. Put on lights, it means that light will cast no shadows on any object. Put on objects, it means that object will not cast a shadow from any light.)

There are also lots of other tricks out there if you check around the forums, including more advanced & optional tricks such as using the [[LOD]] system or [[SEED]] system, or even crazier tricks (cross-leaf func_statics, skybox architecture, Strombine lighting, Camera Cubemapped Visportal Patches, lots of crazy tricks out there), that you don't have to worry about if you're a new mapper but you can ask us about or search for in the forum if you're curious. Generally speaking there are pros and cons trade-offs between performance & dazzle for many things (like lights or visportal placement); so it's good to think about the best performance-dazzle balance for your scene. E.g, lots of highpoly brushwork, lights, & AI can look good in a small or medium room, but may not be worth the performance hit in a big courtyard, and try to find ways to get better performance "for free" without the player noticing anything missing, like smart use of noshadows, monsterclips, and interleaved thinking distances.

== Gameplay Issues that Mappers sometimes Overlook ==

'''Below is a list of common gameplay issues that players sometimes complain about and that mappers & testers sometimes overlook or should at least be aware of.'''

- Players find it very difficult to frob objects (loot, keys, readables) when the frob distance is set too short or the space is awkward (like in a drawer or up on a wall, etc). In testing, please double-check that every frobable object is easy to frob from a comfortable place, and increase the frob distance if it's not, erring on the side of more space. (See the question on making frobbing easier under "Handling Objects" below for more information.)

- Objects can get stuck into brushwork while moving them around.

- Players can get stuck in narrow spaces and can't mantle out, so try to avoid this kind of geometry if possible.

- A very low ceiling can prevent hitting AI with a BJ, so try to avoid it when AI are around.

- Make sure AI have a flee path.

- Some players would like the ability to drop used keys and other inventory items, done by turning the can_be_dropped property to true, unless for gameplay reasons you don't want to.

- Some players don't like long readables that don't get to the point. At least be conscious of how your readables read to a player.

- Think about how you want to handle non-functioning doors (or other "unnatural" situations like windows that can open) in a way that visually or fairly communicates to the player that something is special about this door or window, but isn't too immersion breaking either.

== Issues with Objects ==

'''Q. My streetlight, candle, lamp, light-creating object, causes a weird shadow I want to get rid of.'''

'''A.''' Put the spawnarg "noshadows" "1" on the offending object.

== AI Issues ==

'''Q. My AI will not pass through a visportal no matter how I set up the path nodes.'''

'''A.''' Check that the sides of the visportal use the nodraw texture (except for the portal-face itself of course).

'''Q. How do you get AI to walk on complex terrain patches or func_statics?'''

'''A.''' You can always lay down invisible monsterclip brushes and the AI can walk on it. Overlay with a brush with a "material" clip texture so it causes the right sound for footsteps.'''

== Problems with Patches ==

'''Q. I have 2 curved patches and they're not aligning. What do I do?'''

'''A.''' See this wiki page [[Patch_Troubleshooter]].

'''Q. My patch is rendering strangely, like fractured into slivers.'''

'''A.''' See this wiki page [[Patch_Troubleshooter]].

== Issues with Lighting & Sound ==

'''Q. Some of the parallel lights I use for moonlight aren't giving off any light.'''

'''A.''' This is a known problem with parallel lights. For some reason in some arrangements you get no light at all. Just fiddle with it a bit - move it slightly, change the radii, move the vertex a bit - and it should suddenly work. Once you've got it working then it's stable. Likely the code chokes on certain values in its calculations. ... Also, to help optimize your moonlight, you should adjust the radius so it's only as big as it needs to be. You may also want to move the actual position of the little moon cube in the skybox to match the parallel light (and make sure to fix the texture on it if you mess it up - hint: lock textures before moving cube to make it easy)

= General How-To Editing FAQ =

== Dark Radiant Questions ==

'''Q. How do I see all the default properties already on an object?'''

'''A.''' In the entity inspector there's a checkbox near the top that says "Show Inherited Properties". Click that box.

'''Q. What are some basic units, scales, limits, maxs, and mins of various things when editing?'''

'''A.''' A list of all these things is here: [[Limits,_Max,_Min,_Stats,_etc]].

'''Q. Can I manipulate brushes to resize and reshape them?'''

'''A.''' Yes. In DarkRadiant you can select a brush and push "V" to select verticies to drag and resize, "E" to select edge(s) to drag and resize, and "F" to select face(s) to drag and resize. "Ctrl+#" makes a selected brush be #-sided. You can also use the Brush>Prism and Brush>Cone to convert a brush to those shapes.

'''Q. What are some common DR shortcut commands?'''

'''A.'''
* "H" hides selected items.
* "I" inverts selected.
* "Ctrl+I" inverts a patch's normal.
* "J" brings up entity list.
* "Ctrl+K" makes 1st-selected-entity "target" 2nd-selected-entity.
* "L" brings up light inspector.
* "Ctrl+L" brings up the Layers menu.
* "N" brings up entity inspector.
* "T" brings up texture browser.
* "X" go into clipper mode.
* Brush manipulation modes: are "R" rotate brush, "Q" free-move & resize, "W" translate-move.

'''Q. How do I make my own shortcut key commands?'''

'''A.''' Under the Edit menu, at the bottom is "Keyboard Shortcuts" which allows you to set your own shortcuts.

'''Q. I screwed something up! What do I do?!'''

'''A.''' Ctrl+Z undos. Ctrl+Y redos.

'''Q. Is there a way to organize & simplify building, so I can build one section at a time without other sections getting in the way?'''

'''A.''' DR has a [[Layers]] function that lets you build one "layer" at a time (open with ctrl+L or View>Layers). It also improves DR performance, which is handy as the map gets bigger.

'''Q. How do I set up things like the pre-game shop, the player inventory, and an in-game map?'''

'''A.''' All these things are described in the Startpack Mappers' Guide: [[Startpack_Mappers'_Guide#Ammo.2C_Weapons.2C_Player_Tools.2C_Start_Inventory]], [[Startpack_Mappers'_Guide#Purchase_Shop]], [[Startpack_Mappers'_Guide#Adding_an_In-game_Map_to_your_FM]]

'''Q. How do I put spawnargs on def_attached entities?'''

'''A.''' You can put spawnargs on def_attached entities by using the spawnarg "set SPAWNARGNAME on ATTACHMENTNAME" "value" on the base entity. Here's an example of setting a color property on a flame attachment to a torch "set _color on flame" "0.2 0.2 0.9". Read more here [[Combined_light_entities#Setting_spawnargs]].

'''Q. What's an easy way to find materials in DR?'''

'''A.''' Tip to help find materials in Dark Radiant's materials browser:
# Point to Textures (or any tree).
# Shift + Right key to fully open the tree.
# Type the key letters of what you want to find.
# Up/down arrows to go to next/previous occurrence.
# Esc to get out of input field.
Oh yeah, avoid F3 because that is likely to switch to render mode which in my case crashes DR (but may not if the map is small).

'''Q. How do I make an N-sided brush?'''

'''A.''' A quick way to make an N-sided brush is to highlight the brush and push cntl+N (N being the number of sides for the top face). So if you want a 5-sided brush, highlight it and push cntl+5. But the best way to get the walls of a multi-sided brush to line up seamlessly is still to use the clipper-tool and precisely cut off a slice. (And don't use CSG Subtract unless you know what you're doing and aren't creating a million splinters!)

== Console Questions ==

'''Q. How do I open the console?'''

'''A.''' Open the console with ctrl+alt+~ in a normal game, and just ~ when playing through "map".

'''Q. How do I scroll through the console output?'''

'''A.''' Use the mouse wheel or PageUp/PageDown.

'''Q.What's a list of all the Doom3 Console Commands and CVars?'''

'''A.''' A list of all commands & Cvars is here [http://www.doomwadstation.com/doom3/console/]. Darkmod Cvars are listed here [[Cvars_in_The_Dark_Mod]].

'''Q. What are some *useful* console commands and cvars for editing?'''

'''A.''' Here's one list: [[Console_Useful_Controls]]. Here's a list more tailored to mapping:

Commands:
"'''dmap <name>'''" compiles a map,
"'''give <name>'''" gives the player an item,
"'''god'''" player cannot be harmed,
"'''killmonsters'''" takes out all AI
"'''map <name>'''" loads a map to play,
"'''noclip'''" lets the player go through objects and walls,
"'''notarget'''" let's the player be invisible to AI,
"'''reloadDecls'''" will reload material defs without having to re-start TDM,
"'''reloadimages'''" does the same for lights and
"'''reloadSurface'''" for surfaces,
"'''saveRagdolls'''" saves the positions of all ragdolls to the .map file (see the FAQ under Handling AI),
"'''teleport <name>'''" teleports the player to an entity.
"'''tdm_show_loot'''" Shows loot.
"'''spawn <name>'''" spawns an entity:
spawn atdm:weapon_blackjack
spawn atdm:weapon_shortsword
spawn atdm:ammo_broadhead
spawn atdm:ammo_firearrow
spawn atdm:ammo_gasarrow
spawn atdm:ammo_mossarrow
spawn atdm:ammo_noisemaker
spawn atdm:ammo_ropearrow
spawn atdm:ammo_waterarrow
Append "inv_ammo_amount 50" to any of the above to spawn 50 arrows at once: spawn atdm:ammo_broadhead inv_ammo_amount 50
Cvars (1 turns on, 0 turns off, unless otherwise noted):
"'''com_showFPS 1'''",
"'''r_showLightCount 1'''" (colors shows the number of lights hitting a surface, black = 0, red = 1, blue = 2... etc),
"'''r_showPortals 1'''" (red=closed,green=open) If your portals dont show up they are most likely not sealing.
"'''r_showTris n'''" (n=1) Shows tris rendered directly, (n=2) shows overdrawn tri's, (n=3) shows all tri's, direct and indirect.

== Objectives ==

'''Q. How do I set up a put-object-here objective?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__182924]

'''Q. How do I set up a "ghosting" objective (e.g., you are busted if you are seen.)'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__204695]

== Handling Objects ==

'''Q. How do I attach a door handle to a door?'''

'''A.''' Just position the handle and input "bind" and the door entity ID/name as a spawnarg.

'''Q. How do I make an object into loot?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__182921]

'''Q. How do I make an entity frobable?'''

'''A.''' See the entry for [[Making an Entity frobable]].

'''Q. Ok it's frobable, but doesn't fall or move. How do I make an entity act like a world object?'''

'''A.''' You need to make the object a moveable, see [[Moveables]].

'''Q. How do I get a lever or button to open a door?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__212036]

'''Q. How do I put some text on a sign or wall?'''

'''A.''' You can use this method [http://forums.thedarkmod.com/topic/11159-add-text-to-your-signs-signposts-walls-etc/]

'''Q. How do I bind something to a rope (like a body) so it doesn't fall?'''

'''A.''' Dynamic ropes are unreliable, so it's good to use a func_static like a chain or make a func_static rope from a cylinder brush. For a ragdoll, place the ragdoll so he clips into the func_static. You need to bind the ragdoll to the chain (so the spawnarg is on the ragdoll), with "bind" "func_static_...", where func_static_... is the chain. Or, through DR, you can just select the entity you want to attach (the ragdoll), then also select the thing you want to attach it to (the chain), and in the menus select "Entity" - "Bind selected entities". But it's been reported the clipping does the job, not binding. See this link [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__221262]

'''Q. How do I make something switch from frobable to unfrobable like a used lever, or unfrobable to frobable like contents in a chest or drawer you don't want frobable until it's open?'''

'''A.''' Make a brush around the object with a clip texture and convert it to an atdm:target_set_frobable entity, with the property "start_frobable" 1 or 0 (which mean true or false) depending on your case (it affects everything inside), and a triggering entity, such as the lever or the chest itself, that targets the set_frobable entity that triggers the switch when it's frobbed. For the record, you can also switch the frobability of an object in a script with the command: '''$<entityname>.setFrobable(n);''', where n is "1" to make it frobable and "0" for unfrobable.

'''Q. How do I make breakable glass?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__222734]. You basically convert your glass brush to a func_fracture entity and set the "health" spawnarg to the value you want the glass to break at.

'''Q. What about an object that gets increasingly damaged-looking as you hit it?'''

'''A.''' Use a func_damagable entity, which replaces its model and/or shader with increasingly "damaged" versions (as many stages as you like) when its health goes below the threshold you set with the "health" spawnarg, and you can use "target" to trigger something when damage occurs (such as a sound effect or event). See here for details on the spawnargs involved in setting it up: [http://www.modwiki.net/wiki/Func_damagable_(entity)]

'''Q. How do I make an object that you can frob and it does something or something happens?'''

'''A.''' If it's an object you made from patches or brushes, make it into a frobable func_static, or if it's already a func_static, make sure it's frobable ([[Making an Entity frobable]]). Then give it a Frob response whose effect is a trigger, and give it a "target" spawnarg to the entity that causes your effect when triggered.

'''Q. Can a lever or button target multiple entities?'''

'''A.''' Yes! Use the spawnargs "target1", "target2", "target3", etc, with each entity-target as a value. A quicker way is to use the keyboard shortcut Ctrl+K. Select the button or lever, then select the target-entity and hit Ctrl+K. De-select the target-entity then select the next one, hit Ctrl+K again. Each time adds a new target to the switch. (Many other spawnargs allow you to have multiple entries by numbering them, such as bind and def_attach.)

'''Q. How do I make a rotating entity, like a fan?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__242385]

'''Q. How do I make objects non-solid so they still render but the player can walk through them?'''

'''A.''' Add the spawnarg: noclipmodel 1 to turn them into non-solids.

'''Q. How do I make a firefly or will-o-wisp, basically a glowing ball that floats around?'''

'''A.''' This is a rough explanation to help you get started. A firefly is a func_emitter. Click the model property then use the button bottom right to select a suitable particle effect, possibly tdm_glare_lamp_01.prt. Bind to something invisible that will move it along a path, typically a func_mover with nurb curves used as the path. A tutorial for setting up nurb curves is here [http://www.doom3world.org/phpbb2/viewtopic.php?t=5123].

'''Q. How do I trigger an event from something in the player's inventory?'''

'''A.''' give the object a "target" to trigger and also the property/value: scriptobject InvTriggerScript. If your object does not already go in the inventory then use the entity: items > custom > atdm:moveable_custom_item. If you get a collision model error then ask on the forums for help (or read the wiki entry for [[Moveables]]).

'''Q. How do I teleport an entity?'''

'''A.''' Use targets/atdm:teleport. See this wiki page [[Teleporting_entities]].

'''Q. How do I make a custom inventory item with its own inventory icon graphic?'''

'''A.''' See this entry [[A_-_Z_Beginner_Full_Guide_Page_6#Special_Items]] for setting the inventory category, loot type, inventory name and inventory icon. To repeat the instructions for a custom icon: on the object put the property "inv_icon" with a value "guis/assets/hud/inventory_icons/<name>.tga" (substitute whatever name you gave it for <name>), and package your .pk4 to put your image file in that relative location. You can also see other inventory_icons there and can use an existing one, or package your .pk4 to replace an existing one with your custom one. A method for making an inventory icon is described here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__259172] (be sure to use an alpha channel to make the background transparent, tutorial: [http://www.axialis.com/tutorials/tutorial-misc001.html]).

'''Q. How do make an object that's hard to frob easier to frob?'''

'''A.''' One easy way is to add this property: frobbox_size 5. If it's still hard, see this post for other things you can do. [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__228245]

'''Q. How do I make a candle you can pinch to go out?'''

'''A.''' I made a bunch of pinchable non-moveable candles into my WIP like this:
# Make a func_static candlestick. place light source entity candleflame on it.
# Give the candlestick "frobable 1."
# Give the candlestick S&R response frob, extinguish light and candleflame name.
# You can optionally add another response frob to trigger a speaker with a "snuff" sound effect.
# Done.
You can copy the entity bunch around and all the params should update correctly for the new replica. Frobbing will not relight it: the player needs to relit them with a flame source.

== Handling AI ==

'''Q. How do I make sure a guard can unlock a door?'''

'''A.''' There are a few different ways, explained here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__217915]

'''Q. How do I attach a key or purse to an AI's belt, or similar kinds of attachments?'''

'''A.''' The easiest way is with "bind". Place the key or purse around the belt area where you want it, sticking a little farther out than usual, and rotate it as desired. On the key add the property "bind" with the value of the AI's entity-ID or name, then the property "bindToJoint" with the value "leftHips_dummy" or "rightHips_dummy" as needed. For attaching things in other places (like a ring or hat or necklace), it's the same general principle but you should look up the joint to attach to. A list of all the joint names is here: [[BindToJoint]]. See this wiki entry for more info [[Attaching_Items]]. For another method using def_attach see [[Attaching_Props_to_AI]], and this post for an example of the spawnargs involved [http://forums.thedarkmod.com/topic/13084-ai-attach-keys/page__view__findpost__p__276064]. The issue with def_attach is that the attached thing spawns at its own rotation angle, which might not look great and is tricky to change (if you insist, see [[AI_Attachment_Ingame_Editing]] and [[Cvars_in_The_Dark_Mod#Attachment_related]]). With bind you just place and "bind", and it stays where you put it.

'''Q. What about other kinds of attachments where special animations are involved, like torches and weapons?'''

'''A.''' For these you want to use Def_Attach. See this wiki entry [[Attaching_Props_to_AI]]. For heads & weapons specifically see this wiki entry [[Adding_Heads_and_Weapons_to_AI]]. (You can set spawnargs on the def_attached entities with the method described here [[Combined_light_entities#Setting_spawnargs]].)

'''Q. How do I mute an AI?'''

'''A.''' Give the AI the spawnarg: def_vocal_set atdm:ai_vocal_set_mute. If you only want to mute some barks, you'll have to modify the AI's .def file by hand, taking or commenting out the barks you don't want, and packaging the new def file in your mission's pk4. For coughing and animation based barks, see this post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__224558]

'''Q. Can I hide an AI until I trigger him?'''

'''A.''' No, the spawnarg "hide" doesn't work well with AI (they're made invisible, but still audibly there). Put the AI in a blueroom and use a teleport instead, or a teleporting script command. See the wiki entry for [[Teleporting_entities]]. Note, after teleporting an AI, pathing becomes a problem for it. See this post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__280818] and the previous posts on this issue to make sure the AI can path properly after a teleport.

'''Q. How do I manage AI teams, who is a friend, enemy and neutral?'''

'''A.''' To set the teams, see [[Relations]]. If you want to trigger a change in team with a script, see [[AI_Relations_(Scripting)]]. Another method to switch AI teams using S&R (stim & response) is described here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__256126] and see the entry [[Stim/Response]].

'''Q. How do I make an AI play an animation when I want?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__253169]. There may be other ways possible.

'''Q. How do I set or change the health of AI?'''

'''A.''' AI use the spawnarg "health" to set their hit points. To change it in-game, use a script and the function "setHealth".

'''Q. How do I pose ragdolls so they look naturally placed?'''

'''A.''' Save a backup, pose all the ragdolls in-game, then use the console command saveRagdolls which saves their positions to the .map file. cf. [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__265650].

'''Q. How do I make a scene of AI playing cards?'''

'''A.''' Probably the easiest thing to do is load the prefab (under AI), place it, and adjust it how you want.

'''Q. How do I make an AI frob something?'''

'''A.''' To get an AI to frob something, eg, a lever (doesn't work to pick up and carry) create a path_interact entity. You can include it in a normal pathing patrol. Give it these 2 spawnargs: ent <name of entity you want the AI to frob>; target <next path entity (if any)>. Note that the AI won't walk to this entity; you have to use a path_corner to get him where you want then target to the path_interact to get him to frob.

'''Q. How do I make an AI catch fire?'''

'''A.''' You can bind some unlit fires to an NPC (like a zombie) and shoot it when a fire arrow, he'll erupt in flames, but the flames won't damage him. You could also light him with a candle. I'd bet theres some way to make that actually kill the creature, or at least cause it damage. ... One improvement suggestion: When the the light gets the fire stim, target a trigger multiple, which delays for a 120-240 seconds and then turns the fire off. You could make the fire damaging by starting a trigger timer which applies the stim damage to the target every few seconds. Remember to switch off the timer when the flames are doused.

'''Q. How do I keep an AI ragdoll from sinking into the bed model, e.g., if he's KO'd?'''

'''A.''' I found one way to keep [an unconscious/dead ragdoll body] from sinking into the model below it is to use a platform of nodraw_solid underneath the body. You should be able to place such a brush within the bed model and test it with a ragdoll on the bed. Adjust it's top surface height until the body lays just on top of the bed (then delete the ragdoll)... then a blackjacked AI should be able to stay on top of the bed like the ragdoll did.

== The Player ==

'''Q. How do I do things with the player's inventory, like trigger an inventory item to be deleted, or an item to be added to the inventory, or one item being replaced with another item?'''

'''A.''' You can do all these things with a script (read [[A_Beginner's_Guide_to_Scripting]] and the scripting FAQ below to learn about scripting). Have your triggering mechanism trigger a target_callscriptfunction entity which calls a custom script, then use the appropriate script command in the script on $player1. A list of the commands is here [[Inventory#Scriptsupport]].
Useful commands are (replacing the "Item" variables with the item ID):
* '''$player1.addInvItem(inv_item);''' and
* '''$player1.replaceInvItem(oldItem, newItem);''' (note: If <newItem> is the $null_entity, <oldItem> is just removed and no replacement happens.)
For example, to remove a key from the player's inventory, use a command like: '''$player1.replaceInvItem ($key, $null_entity);'''

'''Q. How do I teleport the player?'''

'''A.''' Use base > info_player_teleport. Give it the spawnarg and value: target info_player_start_1. Give it the spawnarg: angle with a value if you want to force the player to turn to face a particular direction.

'''Q. How can I simulate a crawl for the player to pass under things like tables that he couldn't normally do?'''

'''A.''' See this post [[http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__229174]]

== Scripting ==

'''Q. How do I make a custom script?'''

'''A.''' First read [[A_Beginner's_Guide_to_Scripting]], [[Scripting_basics]], and [[My_first_map_script]] to learn the basics of scripting. You write a custom script as a text file named <mapname>.script and packaged in your .pk4 in the same place as your .map file. Inside it you make your own script object or function (I'll just call them "scripts" from now on, since a "scriptobject" refers to a specific spawnarg in TDM, not the general case as I mean it here) in the format the Beginner's Guide gives you, usually looking like '''void MyScript() { code goes here }'''. Then the game can "call" "threads" of that script that will run until they end or are killed, so you can have more than one thread running the same script concurrently. If you want multiple scripts, put them all in your <mapname>.script file and the game-engine will find them. You run scripts by the script name, not the file name.

'''Q. How do I run a script in-game?'''

'''A.''' A few common ways of calling a script thread in-game are
# creating a target_callscriptfunction entity with the spawnarg: "call" "<name of your script>", then creating some other entity (such as a button or trigger brush) that "targets" that entity;
# creating a button with the property "state_change_callback" "<script>", which runs the script when pushed or triggered,
# Using [[Location_Settings#Script_calls]] to call a script when you enter or leave a location;
# triggering a script with the [[Objectives_Editor]] when you fulfill or fail an objective (possibly a hidden objective only for triggering the script);
# A script can call another thread in itself with the "thread" function; see the command in the link below.
# An entity can call a script when it spawns. Add a property/value either in the .def file or as a spawnarg on the entity: "ScriptEvent void <script>(<parameters>);".
# The script "void main();" is always called at game start. So if you add code under that heading in your script file, it will run at game start.
There are other methods too. (Note, if you call a persistent script, i.e., it runs all game, be especially sure to avoid performance hits, or make it non-persistent if possible, that is, you "kill" it at some point in the game so it doesn't hog resources..)

'''Q. What are script events (aka commands or functions)?'''

'''A.''' A script event is a pre-made object or function that does something for you, usually to some game item you specify, just when you write it in your code (like '''$item.eventX();''' does X to item). Sometimes it wants parameters or arguments to run (the stuff in parentheses) and will give an error if you don't put the arguments in the parentheses in exactly the way it wants, with the right number of them & right data types, etc. And some of them return values too, especially the "get" functions, which are handed over to a variable (e.g., '''X = getValue();''', now X has the value. If X is an entity, you can even act on X as if it's the entity itself. Just be sure the data type of X and Value are the same, e.g. float, or string, or entity, etc, or you'll get an error).

'''Q. What are some common or useful script events for editing?'''

'''A.''' A list of all Doom3 and TDM script events are listed on this wiki page [[TDM_Script_Reference]], including the proper syntax (or this page, but it's down now: [http://www.modwiki.net/wiki/Script_events_%28Doom_3%29]), or also these two files in your Dark Mod folder (open with a text editor): scripts/doom_events.script, scripts/tdm_events.script. Note that TDM has some of its own script events, like setFrobable (in the tdm_events.script list).

A quick short list of common or useful script events good for editing is here: [[Script_Events_User-Friendly_List]], with syntax and description, and including TDM events. It doesn't list all script events and all details, just common & useful ones for actual mapping IMO. If you want the full list, use the TDM_Script_Reference link I gave above.

== World Building ==

'''Q. What's a good way to make caves?'''

'''A.''' Some tips are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__204909] & [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__289484] Instructions for quick-cavern pattern building is here [http://forums.thedarkmod.com/topic/14469-quick-caverns-recipe/page__view__findpost__p__304250]

'''Q. How do I make a good looking roof using clean brushwork, including with an attic inside?'''

'''A.''' Here are descriptions of method that all use a similar trick [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__325945], [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__325944], [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__244109]. The trick is to "cut out" a roof from a square brush using the clipper tool. Avoid rotating brushes to make it by hand. Alternatively, use patches over a rectangular under-structure of BSP brushes, although this is not good if you want a portaled attic.

'''Q. What's a good way for making a city area that performs well?'''

'''A.''' Sotha gave a good method in this post. [http://forums.thedarkmod.com/topic/10003-so-what-are-you-working-on-right-now/page__view__findpost__p__312133]

'''Q. What's a good way for making a forest or a big outdoorsy area?'''

'''A.''' One good method is making large "rooms" in the shape of a big oval cylinder with very high natural-looking "rocky" & skybox walls and uneven ground using patches, filling it with trees and hiding some of the walls behind trees and greenery (you could also fill it with thick cylinder brushes of different sizes with bark texture to look like more trees, and place branches coming off them or to make a canopy), and possibly filling it with tons of grass (using [[SEED]]) and rocks and streams, with visportaled openings at "kiss points" in the walls to other large oval rooms at different orientations (maybe 2-5 connections per oval) so there's a dense web of interconnected forested rooms that (sort of) appear to be one big dense forest to the player. Some useful things to use are the [[Object_detail]], [[SEED]], and [[LOD]] systems. See the blueprint for the Thief 2 level Trail of Blood for a rough idea: [http://thief.wikia.com/wiki/T2_M10_Trail_of_Blood?file=T2_m10a_editor_colored.gif]. For good examples in Dark Radiant, look at the construction of mission 3 of No Honor Among Thieves ("No Honor Among Anyone") and Shadowhide's slenderman forest map. (Somebody post links to screenshots of those maps in DR, or remind me to.)

'''Q. How do I make uneven ground?'''

'''A.''' One method is by burying patches into the ground that stick out and make the ground lumpy as described here [http://forums.thedarkmod.com/topic/13338-newbie-mapper-tip-making-uneven-ground/page__view__findpost__p__274917]. For more encompassing unevenness, you can use much larger patches laid over square caulk brushes underneath that seal the leaf to make the entire ground uneven.

'''Q. How do I make a natural looking road where there isn't a sharp seam between the road material and grass but a nice fading transition?'''

'''A.''' See the Wiki page for [[Roads]].

'''Q. How do I make curved ceilings and archways?'''

'''A.''' Use patches. Here's a list of some good tutorials for this sort of thing [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__254764]. Also look at this wiki page [[Patches#Archways]].

'''Q. What's a way to get good-looking fog in my mission?'''

'''A.''' There are numerous values to make good fog. The setup for the fog from Fidcal's Heart mission is here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__248277].

'''Q. What are some tips to making a better looking map?'''

'''A.''' See this wiki entry [[10_Simple_Tricks_for_Better_Looking_Maps]].

'''Q. What's a good method or plan-of-action for building?'''

'''A.''' This is a matter of personal preference, but a method that professionals use is called the "stepwise refinement" method. It means you build the *entire* space of your mission first in rough blocks (so you have it all planned out first), then refine the whole thing in increasingly more detailed steps section by section, leaving the most fine detailing towards the end. It can help to use DR's Layer system to organize your building by sections too, without other sections interfering. Also, when you're drawing your map, think about arranging space into winding "rooms" (so there's no long lines of sight), even outside with tunnels, walls and skybox; and think about visPortal placement right at the start. Also think about the gameplay-performance balance of shadowing-lights & AI when thinking about placing them.

'''Q. How do I cleanly connect two brush edges meeting together, especially at a diagonal?'''

'''A.''' See this post [[http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__257111]].

'''Q. What's a method for building very fast & efficiently?'''

'''A.''' Sotha came up with "modular" approach where you build a few stock modules of architecture that you can combine to make a lot of geometry very quickly and efficiently. Here's his description: [http://forums.thedarkmod.com/topic/12833-sir-taffsalots-mapping-thread/page__view__findpost__p__290747]

'''Q. How do I make a good looking waterfall?'''

'''A.''' There's a discussion about this in this thread [http://forums.thedarkmod.com/topic/11901-waterfalls/page__pid__303963#entry303963]. For a small waterfall, a white foamy particle effect raining down by itself looks good. You can copy Bikerdude's example from St. Alban's Cathedral. [http://www.youtube.com/watch?v=gIrZDpc1m68]. For a bigger waterfall, people talked about a combination of a flowing vertical water block with the foamy particle effect towards the bottom.

'''Q. How do I make a nice little pond.'''

'''A.''' See this wiki entry [[How_to_create_a_pond]]. This thread [http://forums.thedarkmod.com/topic/14647-how-can-i-make-a-realistic-looking-pond/page__view__findpost__p__308916] has discussion on it.

== Patches! ==

'''Q. Is it possible to split patches?'''

'''A.''' See this tutorial on it [[Patch_Splitting_-_Basic_Tutorial]].

'''Q. How do I bend patches?'''

'''A.''' See the instructions at [[Patches#Bending_Patches.2C_Curves.2C_L-shapes.2C_etc]] (Here's another small tutorial in a post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__277350].)

'''Q. I want to use a patch to round off a corner.'''

'''A.''' See this part of the Patch wiki page [[Patches#Round_and_Soft]].

'''Q. How can I make a perfect circle with patches?'''

'''A.''' Select verts of 4 corners, select the "rotate and scale" tool, and use the value "0.9428" to scale "up" (actually down) in the 2 corresponding axis of the scale tool. See this post [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__279356].

'''Q. How do I make a dome or sphere?'''

'''A.''' Make a cone patch and drag down the top vertex to form a dome. Invert the matrix if you want an internal dome or thicken if you want it to be visible inside and out. A sphere is just two of these stuck together. Also tweak the tesselation in patch inspector if it is too chunky. You can have fun with the textures though; try fit. If you totally flatten the dome you have a disc which can produce some nice texture effects, eg, the marble floor centrepiece or a round rug. Drag a side to make it oval. See this post for a picture [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__233107].

'''Q. How do you align a texture on a curved patch?'''

'''A.''' When you want to align properly texture to curved patch like this one in the image [NB: image is missing], divide a brush according to the angle of the patch then use it's shader for your purpose. ... I made it with one edge is at one end of the curved patch and the other edge is at the other end. It gets distortions without this way.

== Events and SFX ==

'''Q. How do I trigger an earthquake event?'''

'''A.''' Earthquakes can be done with a speaker. Just use the spawnarg "s_shakes" "1" on the speaker, and the screen will shake violently however loud the sound gets.

'''Q. How do I emulate something like a blizzard or dust storm?'''

'''A.''' Doom3 made a dust storm area, and the same method can be used to make a blizzard, so it's possible. I'm leaving this here to look up instructions for future reference.

'''Q. How do I make the screen fade to black (or some other color), or from black back to the game.'''

'''A.''' Create entity: [[Triggers#trigger_fade|Trigger_Fade]]. Adjust "fadeTime" and "fadeColor" spawnargs as desired.

== Textures ==

'''Q. What's a quick way to align textures between two surfaces?'''

'''A.''' For two brushes, select the first surface, then '''edit --> copy shader''', then click on the second surface and '''edit --> paste shader'''. This will seamlessly match the 2nd surface to the texture of the 1st. DR also comes with a useful tool for texture alignment, [[Texture_Tool]], which you bring up with Ctrl+Alt+T. If it's textures on two patches, you can follow these directions: [http://forums.thedarkmod.com/topic/14034-tutorial-for-road-creation/page__view__findpost__p__294114]

'''Q. How do I randomize the position of textures on multiple brushes, e.g., for a row of stairs or pillars all with the same texture that I want to look different?'''

'''A.''' Select multiple faces and in the surface inspector, press the natural button once you set the scale properly.

'''Q. Can I blend textures?'''

'''A.''' Yes. This is particularly good for dirtying some textures up by blending in a grime texture. You can blend textures with a custom material file. Link to instructions coming. Also see the entry for [[Basic_Material_File]].

'''Q. How about blending texture transitions so there isn't a sharp seam, e.g., for a dirt path in grass?'''

'''A1.''' DR comes with grass edge transition decal patches to overlay the hard edges. Read how to set it up here [[Grass_Edges]], or a more detailed tutorial on making roads here [[Roads]].

'''A2.''' In NHAT blended terrain was made from patches broken into segments then exported as ASE models. Then the models were vertex painted in Blender and imported back into Dark Radiant. See this tutorial [[DrVertexBlend_(tutorial)]].

'''Q. How do I set the color for some textures (like glowing mushrooms) and make lightbulbs go dark when turned off?

'''A.''' "Colorme" textures allow you to set the color with a spawnarg. So e.g. for colored mushrooms, choose a colorme skin with the spawnarg like "skin" "mushroom_selflit_green_colorme" and choose the color with a spawnarg like "_color" "0.24 0.50 0.40" (where the value is the RGB values you want). For lightbulbs you can trigger a colorme texture switch with the lightswitch (so it switches between "lit up" and "black"). Instructions on that coming.

'''Q. What's a fast way to put different textures on a lot of objects?'''

'''A.''' 1. Click the mouse wheel on the texture to copy it. 2. To paste it naturally (i.e., in a random position): shift+mousewheel click. 3. To just paste it: ctrl+mousewheel click.

'''Q. Can you tile a texture a specific number of times to fit a surface?'''

'''A.''' When you want to tile a texture a certain number of times, enter the values 1/X and 1/Y (you need to compute them in your head) in the little boxes in the surface inspector, then press "Fit". It will tile your texture horizontally X times and vertically Y times. You can also enter things like "2" and "1" and get a texture that only occupies half of the width. You can then use the "Right" or "Left" buttons to align it quickly at the ends. Pro-tip: Press CTRL+ALT+T to open the texture tool, it allows super quick aligning of textures on patches. Esp. useful for decals where the decal texture consists of multiple decals.

== Readables & GUIs ==

'''Q. How do I put custom art in a book or scroll, like a picture?'''

'''A.''' Use a custom .gui. Here's a rough idea to get you started [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__263836]. I'll try to put better instructions in later.

'''Q. How do I trigger a text message to pop up and say something?'''

'''A.''' Create an entity: darkmod > targets > atdm:gui_message and give it the properties/values that you want. Popups will explain each one. You can target it with a triggering entity or trigger it from a script or any other triggering mechanism. An example is here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__256592]

== Lighting and Sound ==

'''Q. How do I add music or ambient sounds?''' '''Q. Can I dynamically adjust the ambient lighting?'''

'''A.''' For both of these things, check out the article for [[Location Settings]]

{{editing|sort=Editing FAQ (Troubleshooting & How-To)}} {{tutorial-editing|sort=Editing FAQ (Troubleshooting & How-To)}} {{darkradiant|sort=Editing FAQ (Troubleshooting & How-To)}}

'''Q. How do I set up Reverb (EAX) settings for my rooms? (E.g., the echo of a large hall, etc.)'''

'''A.''' Create a text file and name it <mapname>.eax; place it in your .pk4 with your .map file; and in it create entries by location name with the values you want for that location. See this wiki entry to see the format & values [[Setting_Reverb_Data_of_Rooms_(EAX)]].

Editing FAQ - Troubleshooting & How-To

2014-08-08T03:24:36Z

Demagogue: /* Scripting */

Below are some common issues and questions mappers have had in the Editor's Guild forum with common solutions. Some of this assumes you've already gone through the [[A_-_Z_Beginner_Full_Guide_Start_Here!]], [[Startpack_Mappers'_Guide]], and [[Dark_Radiant_Must_Know_Basic_Intro]]. (If you know a FAQ not here and worth going in this list, and you know the right answer(!), or you can improve an existing answer, please add it if you have edit control or PM it to a team-member if you don't.)

= Troubleshooting FAQ =

== Rendering & VisPortal Issues ==

'''Q. Some of my brushes have disappeared or turned black and won't render.'''

'''A.''' This can happen when two touching brushes around the seam are not perfectly flush with one another and the rendering hiccups for those brushes & brushes behind it, either there's a tiny wedge or overlap or gap or weird angle between them. The usual solution is to make sure the brushes are snapped to the grid and perfectly flush against one another, or more generally to simplify the brushwork around the seam of the disappearing brushes.

'''Q. My visportal is not showing up or not closing like it should (you can check this with by typing "r_showportals 1" in the console. The portal edge will show green when open and red when closed.).'''

'''A.''' A common reason for that is that the two areas separated by the portal are not hermetically sealed and there's an internal leak, either (1) there may be an unportaled gap between the two, possibly covered up by func_static (which do not seal) or possibly caused by an inadvertent hole created by the first FAQ question above, or (2) an internal leak can happen when all sides of the visportal are not buried in or flush against sealing brushes, and there's a gap between the visportal and brush, or possibly even a tiny gap just touching the visportal side is enough to break it. A way to check if there's an internal leak, and locating it if there is, is described here: [[Visportals#Trouble-shooting]]. Other reasons it might fail are also described there (such as accidentally changing a nodraw texture to something else).

'''Q. I can see other rooms behind a mirror (or any reflective surface) through it, instead of just a reflection.'''

'''A.''' The area behind a mirror should be in a separate leaf (visportaled area) behind a closed visportal so it doesn't render. This problem usually means the two areas aren't in separate leafs, the portal isn't closed, or there's an internal leak between the areas in front of and behind the mirror.

'''Q. Help! I'm having rendering & visPortal issues all over the place ... broken portals, sparkly lines, disappearing brushes, z-fighting, uneven walls, etc.'''

'''A.''' As a general piece of advice, messy brushwork leads to trouble one way or another. To keep your brushwork clean:
* keep snapped to the grid (Ctrl+G toggles) & stay away from small grid levels (Typing a number or Plus/Minus changes the grid scale; 8 is a good starting grid; staying at or above 2 or 4 is fine for most stuff; going below 1 is usually just for special situations).
* Make brush intersections perfectly flush.
* Stay away from unnecessary tiny brushes & wedges (leave detail work to func_statics; brushes are for closing off leafs and the void. Of course you can do fine detail work with brushes & convert them to a func_static).
* Don't use the "CGS Subtract" tool if it will shatter the brush into tiny slivers; use the cut tool instead (open by pushing "X").
* You can use patches for uneven geometry with square brushes underneath textured with caulk.
* When rotating geometry, avoid weird angles when you can (where vertexes end up off the grid), and for multi-brush structures, build the whole thing first *then* rotate it all together instead of rotating & placing each brush individually.
These aren't rules set in concrete if you want to do something special once in a while, but general rules of thumb that will make life a lot easier if you generally stick to them.

== Crashes and Warnings ==

'''Q. My map has a leak in it, but a pointfile either isn't generated or doesn't make sense. (A pointfile is generated when dmap occurs and there's a leak, then you open DarkRadient and click File>Pointfile to see it. It normally runs a red line that ends in the void, pointing out the leak).'''

'''A.''' Make sure a gap isn't covered up with func_statics. If the origin of a model is in the void it will also cause a leak with a non-sense pointfile. Read more on the [[Leaking maps]] page.

'''Q. How do I scroll up through the console output to see what a problem was during dmap or map or in-game?'''

'''A.''' Use the mouse wheel or PageUp/Down to scroll through the console.

'''Q. I'm getting an error message "warning: aas is out of date" once my map has loaded. What does it mean and what do I do?'''

'''A.''' The AAS is for AI pathfinding. It usually means you changed brushwork and started a map without dmapping first. The solution is to dmap. If you dmap and still get the warning, delete your .aasxx, .proc, and .cm files in the maps folder and dmap again. If you're still getting a warning, then it could be a sign that something in your map is breaking the AAS pathfinding. Try monsterclipping tricky areas for the AI to path (like around objects and uneven ground) or clean up messy brushwork that might break the dmapping like sliver brushes.

'''Q. I have encountered a malloc failure error while dmapping my level. Instead of finishing with the dmap operation, it crashes midway with an error message.'''

'''A1.''' One solution to this is given in the Dmap wiki entry here: [[Dmap#Malloc_Errors]].

'''A2.''' This is what I've done to fix this exact issue. Open the map in DarkRadiant, select everything, copy to clipboard. Open another instance of DarkRadiant and paste from clipboard. Save as new filename and dmap new file and that has worked 3 times now with random unresolvable crashes.

'''A3.''' GC and I have found correlations between visportalling and mAlloc errors. Time to re-arrange your visportals. In NHAT, we had many malloc problems until we retooled how each area was portaled. Originally, every other visleaf had tons of entities, while half had hardly any. That's not neccessarily bad, but it strains the dmapper when one or two visleafs are cluttered with entities that really bloat your mapname.proc file. We added a few more portals to even out entity distribution, and dmap was happy again.

== Performance Issues ==

'''Q. My map is so slow. How do I improve performance?'''

'''A.''' See these wiki entry: [[Performance:_Essential_Must-Knows]]. Tips include:
* Reduce AI [[Pathfinding]] with Monsterclipping helps performance, simplifying complex bumpy surfaces into 1 smooth monsterclipped surface (or raise the monsterclip height to be inside the ceiling and there is no pathfinding computation at all), or excluding entire surfaces AI should never walk on, like detail brushwork or some roofs.
* Use [[Interleaved_Thinking_optimization]]. Reducing AI think-time helps performance quite a bit.
* break-up long lines of sight,
* improve visportal & leaf placement (so less architecture is rendered at a time),
* use fewer AI,
* convert ornamental brushwork into func_static,
* reduce the overlap of light sources on surfaces by adjusting their placement & reducing their light-radius. (Every time a new light hits a surface, it's another render pass. So 4 lights hitting a surface processes it 4 times. If only 1 light hit it, its lighting is processed in 1/4 the time), and
* set objects and lights to "noshadow" if it won't be noticable to the player or affect gameplay (possibly in combination with low-poly shadow meshes or shadowy decals. Note that "noshadow" has two jobs. Put on lights, it means that light will cast no shadows on any object. Put on objects, it means that object will not cast a shadow from any light.)

There are also lots of other tricks out there if you check around the forums, including more advanced & optional tricks such as using the [[LOD]] system or [[SEED]] system, or even crazier tricks (cross-leaf func_statics, skybox architecture, Strombine lighting, Camera Cubemapped Visportal Patches, lots of crazy tricks out there), that you don't have to worry about if you're a new mapper but you can ask us about or search for in the forum if you're curious. Generally speaking there are pros and cons trade-offs between performance & dazzle for many things (like lights or visportal placement); so it's good to think about the best performance-dazzle balance for your scene. E.g, lots of highpoly brushwork, lights, & AI can look good in a small or medium room, but may not be worth the performance hit in a big courtyard, and try to find ways to get better performance "for free" without the player noticing anything missing, like smart use of noshadows, monsterclips, and interleaved thinking distances.

== Gameplay Issues that Mappers sometimes Overlook ==

'''Below is a list of common gameplay issues that players sometimes complain about and that mappers & testers sometimes overlook or should at least be aware of.'''

- Players find it very difficult to frob objects (loot, keys, readables) when the frob distance is set too short or the space is awkward (like in a drawer or up on a wall, etc). In testing, please double-check that every frobable object is easy to frob from a comfortable place, and increase the frob distance if it's not, erring on the side of more space. (See the question on making frobbing easier under "Handling Objects" below for more information.)

- Objects can get stuck into brushwork while moving them around.

- Players can get stuck in narrow spaces and can't mantle out, so try to avoid this kind of geometry if possible.

- A very low ceiling can prevent hitting AI with a BJ, so try to avoid it when AI are around.

- Make sure AI have a flee path.

- Some players would like the ability to drop used keys and other inventory items, done by turning the can_be_dropped property to true, unless for gameplay reasons you don't want to.

- Some players don't like long readables that don't get to the point. At least be conscious of how your readables read to a player.

- Think about how you want to handle non-functioning doors (or other "unnatural" situations like windows that can open) in a way that visually or fairly communicates to the player that something is special about this door or window, but isn't too immersion breaking either.

== Issues with Objects ==

'''Q. My streetlight, candle, lamp, light-creating object, causes a weird shadow I want to get rid of.'''

'''A.''' Put the spawnarg "noshadows" "1" on the offending object.

== AI Issues ==

'''Q. My AI will not pass through a visportal no matter how I set up the path nodes.'''

'''A.''' Check that the sides of the visportal use the nodraw texture (except for the portal-face itself of course).

'''Q. How do you get AI to walk on complex terrain patches or func_statics?'''

'''A.''' You can always lay down invisible monsterclip brushes and the AI can walk on it. Overlay with a brush with a "material" clip texture so it causes the right sound for footsteps.'''

== Problems with Patches ==

'''Q. I have 2 curved patches and they're not aligning. What do I do?'''

'''A.''' See this wiki page [[Patch_Troubleshooter]].

'''Q. My patch is rendering strangely, like fractured into slivers.'''

'''A.''' See this wiki page [[Patch_Troubleshooter]].

== Issues with Lighting & Sound ==

'''Q. Some of the parallel lights I use for moonlight aren't giving off any light.'''

'''A.''' This is a known problem with parallel lights. For some reason in some arrangements you get no light at all. Just fiddle with it a bit - move it slightly, change the radii, move the vertex a bit - and it should suddenly work. Once you've got it working then it's stable. Likely the code chokes on certain values in its calculations. ... Also, to help optimize your moonlight, you should adjust the radius so it's only as big as it needs to be. You may also want to move the actual position of the little moon cube in the skybox to match the parallel light (and make sure to fix the texture on it if you mess it up - hint: lock textures before moving cube to make it easy)

= General How-To Editing FAQ =

== Dark Radiant Questions ==

'''Q. How do I see all the default properties already on an object?'''

'''A.''' In the entity inspector there's a checkbox near the top that says "Show Inherited Properties". Click that box.

'''Q. What are some basic units, scales, limits, maxs, and mins of various things when editing?'''

'''A.''' A list of all these things is here: [[Limits,_Max,_Min,_Stats,_etc]].

'''Q. Can I manipulate brushes to resize and reshape them?'''

'''A.''' Yes. In DarkRadiant you can select a brush and push "V" to select verticies to drag and resize, "E" to select edge(s) to drag and resize, and "F" to select face(s) to drag and resize. "Ctrl+#" makes a selected brush be #-sided. You can also use the Brush>Prism and Brush>Cone to convert a brush to those shapes.

'''Q. What are some common DR shortcut commands?'''

'''A.'''
* "H" hides selected items.
* "I" inverts selected.
* "Ctrl+I" inverts a patch's normal.
* "J" brings up entity list.
* "Ctrl+K" makes 1st-selected-entity "target" 2nd-selected-entity.
* "L" brings up light inspector.
* "Ctrl+L" brings up the Layers menu.
* "N" brings up entity inspector.
* "T" brings up texture browser.
* "X" go into clipper mode.
* Brush manipulation modes: are "R" rotate brush, "Q" free-move & resize, "W" translate-move.

'''Q. How do I make my own shortcut key commands?'''

'''A.''' Under the Edit menu, at the bottom is "Keyboard Shortcuts" which allows you to set your own shortcuts.

'''Q. I screwed something up! What do I do?!'''

'''A.''' Ctrl+Z undos. Ctrl+Y redos.

'''Q. Is there a way to organize & simplify building, so I can build one section at a time without other sections getting in the way?'''

'''A.''' DR has a [[Layers]] function that lets you build one "layer" at a time (open with ctrl+L or View>Layers). It also improves DR performance, which is handy as the map gets bigger.

'''Q. How do I set up things like the pre-game shop, the player inventory, and an in-game map?'''

'''A.''' All these things are described in the Startpack Mappers' Guide: [[Startpack_Mappers'_Guide#Ammo.2C_Weapons.2C_Player_Tools.2C_Start_Inventory]], [[Startpack_Mappers'_Guide#Purchase_Shop]], [[Startpack_Mappers'_Guide#Adding_an_In-game_Map_to_your_FM]]

'''Q. How do I put spawnargs on def_attached entities?'''

'''A.''' You can put spawnargs on def_attached entities by using the spawnarg "set SPAWNARGNAME on ATTACHMENTNAME" "value" on the base entity. Here's an example of setting a color property on a flame attachment to a torch "set _color on flame" "0.2 0.2 0.9". Read more here [[Combined_light_entities#Setting_spawnargs]].

'''Q. What's an easy way to find materials in DR?'''

'''A.''' Tip to help find materials in Dark Radiant's materials browser:
# Point to Textures (or any tree).
# Shift + Right key to fully open the tree.
# Type the key letters of what you want to find.
# Up/down arrows to go to next/previous occurrence.
# Esc to get out of input field.
Oh yeah, avoid F3 because that is likely to switch to render mode which in my case crashes DR (but may not if the map is small).

'''Q. How do I make an N-sided brush?'''

'''A.''' A quick way to make an N-sided brush is to highlight the brush and push cntl+N (N being the number of sides for the top face). So if you want a 5-sided brush, highlight it and push cntl+5. But the best way to get the walls of a multi-sided brush to line up seamlessly is still to use the clipper-tool and precisely cut off a slice. (And don't use CSG Subtract unless you know what you're doing and aren't creating a million splinters!)

== Console Questions ==

'''Q. How do I open the console?'''

'''A.''' Open the console with ctrl+alt+~ in a normal game, and just ~ when playing through "map".

'''Q. How do I scroll through the console output?'''

'''A.''' Use the mouse wheel or PageUp/PageDown.

'''Q.What's a list of all the Doom3 Console Commands and CVars?'''

'''A.''' A list of all commands & Cvars is here [http://www.doomwadstation.com/doom3/console/]. Darkmod Cvars are listed here [[Cvars_in_The_Dark_Mod]].

'''Q. What are some *useful* console commands and cvars for editing?'''

'''A.''' Here's one list: [[Console_Useful_Controls]]. Here's a list more tailored to mapping:

Commands:
"'''dmap <name>'''" compiles a map,
"'''give <name>'''" gives the player an item,
"'''god'''" player cannot be harmed,
"'''killmonsters'''" takes out all AI
"'''map <name>'''" loads a map to play,
"'''noclip'''" lets the player go through objects and walls,
"'''notarget'''" let's the player be invisible to AI,
"'''reloadDecls'''" will reload material defs without having to re-start TDM,
"'''reloadimages'''" does the same for lights and
"'''reloadSurface'''" for surfaces,
"'''saveRagdolls'''" saves the positions of all ragdolls to the .map file (see the FAQ under Handling AI),
"'''teleport <name>'''" teleports the player to an entity.
"'''tdm_show_loot'''" Shows loot.
"'''spawn <name>'''" spawns an entity:
spawn atdm:weapon_blackjack
spawn atdm:weapon_shortsword
spawn atdm:ammo_broadhead
spawn atdm:ammo_firearrow
spawn atdm:ammo_gasarrow
spawn atdm:ammo_mossarrow
spawn atdm:ammo_noisemaker
spawn atdm:ammo_ropearrow
spawn atdm:ammo_waterarrow
Append "inv_ammo_amount 50" to any of the above to spawn 50 arrows at once: spawn atdm:ammo_broadhead inv_ammo_amount 50
Cvars (1 turns on, 0 turns off, unless otherwise noted):
"'''com_showFPS 1'''",
"'''r_showLightCount 1'''" (colors shows the number of lights hitting a surface, black = 0, red = 1, blue = 2... etc),
"'''r_showPortals 1'''" (red=closed,green=open) If your portals dont show up they are most likely not sealing.
"'''r_showTris n'''" (n=1) Shows tris rendered directly, (n=2) shows overdrawn tri's, (n=3) shows all tri's, direct and indirect.

== Objectives ==

'''Q. How do I set up a put-object-here objective?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__182924]

'''Q. How do I set up a "ghosting" objective (e.g., you are busted if you are seen.)'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__204695]

== Handling Objects ==

'''Q. How do I attach a door handle to a door?'''

'''A.''' Just position the handle and input "bind" and the door entity ID/name as a spawnarg.

'''Q. How do I make an object into loot?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__182921]

'''Q. How do I make an entity frobable?'''

'''A.''' See the entry for [[Making an Entity frobable]].

'''Q. Ok it's frobable, but doesn't fall or move. How do I make an entity act like a world object?'''

'''A.''' You need to make the object a moveable, see [[Moveables]].

'''Q. How do I get a lever or button to open a door?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__212036]

'''Q. How do I put some text on a sign or wall?'''

'''A.''' You can use this method [http://forums.thedarkmod.com/topic/11159-add-text-to-your-signs-signposts-walls-etc/]

'''Q. How do I bind something to a rope (like a body) so it doesn't fall?'''

'''A.''' Dynamic ropes are unreliable, so it's good to use a func_static like a chain or make a func_static rope from a cylinder brush. For a ragdoll, place the ragdoll so he clips into the func_static. You need to bind the ragdoll to the chain (so the spawnarg is on the ragdoll), with "bind" "func_static_...", where func_static_... is the chain. Or, through DR, you can just select the entity you want to attach (the ragdoll), then also select the thing you want to attach it to (the chain), and in the menus select "Entity" - "Bind selected entities". But it's been reported the clipping does the job, not binding. See this link [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__221262]

'''Q. How do I make something switch from frobable to unfrobable like a used lever, or unfrobable to frobable like contents in a chest or drawer you don't want frobable until it's open?'''

'''A.''' Make a brush around the object with a clip texture and convert it to an atdm:target_set_frobable entity, with the property "start_frobable" 1 or 0 (which mean true or false) depending on your case (it affects everything inside), and a triggering entity, such as the lever or the chest itself, that targets the set_frobable entity that triggers the switch when it's frobbed. For the record, you can also switch the frobability of an object in a script with the command: '''$<entityname>.setFrobable(n);''', where n is "1" to make it frobable and "0" for unfrobable.

'''Q. How do I make breakable glass?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__222734]. You basically convert your glass brush to a func_fracture entity and set the "health" spawnarg to the value you want the glass to break at.

'''Q. What about an object that gets increasingly damaged-looking as you hit it?'''

'''A.''' Use a func_damagable entity, which replaces its model and/or shader with increasingly "damaged" versions (as many stages as you like) when its health goes below the threshold you set with the "health" spawnarg, and you can use "target" to trigger something when damage occurs (such as a sound effect or event). See here for details on the spawnargs involved in setting it up: [http://www.modwiki.net/wiki/Func_damagable_(entity)]

'''Q. How do I make an object that you can frob and it does something or something happens?'''

'''A.''' If it's an object you made from patches or brushes, make it into a frobable func_static, or if it's already a func_static, make sure it's frobable ([[Making an Entity frobable]]). Then give it a Frob response whose effect is a trigger, and give it a "target" spawnarg to the entity that causes your effect when triggered.

'''Q. Can a lever or button target multiple entities?'''

'''A.''' Yes! Use the spawnargs "target1", "target2", "target3", etc, with each entity-target as a value. A quicker way is to use the keyboard shortcut Ctrl+K. Select the button or lever, then select the target-entity and hit Ctrl+K. De-select the target-entity then select the next one, hit Ctrl+K again. Each time adds a new target to the switch. (Many other spawnargs allow you to have multiple entries by numbering them, such as bind and def_attach.)

'''Q. How do I make a rotating entity, like a fan?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__242385]

'''Q. How do I make objects non-solid so they still render but the player can walk through them?'''

'''A.''' Add the spawnarg: noclipmodel 1 to turn them into non-solids.

'''Q. How do I make a firefly or will-o-wisp, basically a glowing ball that floats around?'''

'''A.''' This is a rough explanation to help you get started. A firefly is a func_emitter. Click the model property then use the button bottom right to select a suitable particle effect, possibly tdm_glare_lamp_01.prt. Bind to something invisible that will move it along a path, typically a func_mover with nurb curves used as the path. A tutorial for setting up nurb curves is here [http://www.doom3world.org/phpbb2/viewtopic.php?t=5123].

'''Q. How do I trigger an event from something in the player's inventory?'''

'''A.''' give the object a "target" to trigger and also the property/value: scriptobject InvTriggerScript. If your object does not already go in the inventory then use the entity: items > custom > atdm:moveable_custom_item. If you get a collision model error then ask on the forums for help (or read the wiki entry for [[Moveables]]).

'''Q. How do I teleport an entity?'''

'''A.''' Use targets/atdm:teleport. See this wiki page [[Teleporting_entities]].

'''Q. How do I make a custom inventory item with its own inventory icon graphic?'''

'''A.''' See this entry [[A_-_Z_Beginner_Full_Guide_Page_6#Special_Items]] for setting the inventory category, loot type, inventory name and inventory icon. To repeat the instructions for a custom icon: on the object put the property "inv_icon" with a value "guis/assets/hud/inventory_icons/<name>.tga" (substitute whatever name you gave it for <name>), and package your .pk4 to put your image file in that relative location. You can also see other inventory_icons there and can use an existing one, or package your .pk4 to replace an existing one with your custom one. A method for making an inventory icon is described here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__259172] (be sure to use an alpha channel to make the background transparent, tutorial: [http://www.axialis.com/tutorials/tutorial-misc001.html]).

'''Q. How do make an object that's hard to frob easier to frob?'''

'''A.''' One easy way is to add this property: frobbox_size 5. If it's still hard, see this post for other things you can do. [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__228245]

'''Q. How do I make a candle you can pinch to go out?'''

'''A.''' I made a bunch of pinchable non-moveable candles into my WIP like this:
# Make a func_static candlestick. place light source entity candleflame on it.
# Give the candlestick "frobable 1."
# Give the candlestick S&R response frob, extinguish light and candleflame name.
# You can optionally add another response frob to trigger a speaker with a "snuff" sound effect.
# Done.
You can copy the entity bunch around and all the params should update correctly for the new replica. Frobbing will not relight it: the player needs to relit them with a flame source.

== Handling AI ==

'''Q. How do I make sure a guard can unlock a door?'''

'''A.''' There are a few different ways, explained here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__217915]

'''Q. How do I attach a key or purse to an AI's belt, or similar kinds of attachments?'''

'''A.''' The easiest way is with "bind". Place the key or purse around the belt area where you want it, sticking a little farther out than usual, and rotate it as desired. On the key add the property "bind" with the value of the AI's entity-ID or name, then the property "bindToJoint" with the value "leftHips_dummy" or "rightHips_dummy" as needed. For attaching things in other places (like a ring or hat or necklace), it's the same general principle but you should look up the joint to attach to. A list of all the joint names is here: [[BindToJoint]]. See this wiki entry for more info [[Attaching_Items]]. For another method using def_attach see [[Attaching_Props_to_AI]], and this post for an example of the spawnargs involved [http://forums.thedarkmod.com/topic/13084-ai-attach-keys/page__view__findpost__p__276064]. The issue with def_attach is that the attached thing spawns at its own rotation angle, which might not look great and is tricky to change (if you insist, see [[AI_Attachment_Ingame_Editing]] and [[Cvars_in_The_Dark_Mod#Attachment_related]]). With bind you just place and "bind", and it stays where you put it.

'''Q. What about other kinds of attachments where special animations are involved, like torches and weapons?'''

'''A.''' For these you want to use Def_Attach. See this wiki entry [[Attaching_Props_to_AI]]. For heads & weapons specifically see this wiki entry [[Adding_Heads_and_Weapons_to_AI]]. (You can set spawnargs on the def_attached entities with the method described here [[Combined_light_entities#Setting_spawnargs]].)

'''Q. How do I mute an AI?'''

'''A.''' Give the AI the spawnarg: def_vocal_set atdm:ai_vocal_set_mute. If you only want to mute some barks, you'll have to modify the AI's .def file by hand, taking or commenting out the barks you don't want, and packaging the new def file in your mission's pk4. For coughing and animation based barks, see this post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__224558]

'''Q. Can I hide an AI until I trigger him?'''

'''A.''' No, the spawnarg "hide" doesn't work well with AI (they're made invisible, but still audibly there). Put the AI in a blueroom and use a teleport instead, or a teleporting script command. See the wiki entry for [[Teleporting_entities]]. Note, after teleporting an AI, pathing becomes a problem for it. See this post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__280818] and the previous posts on this issue to make sure the AI can path properly after a teleport.

'''Q. How do I manage AI teams, who is a friend, enemy and neutral?'''

'''A.''' To set the teams, see [[Relations]]. If you want to trigger a change in team with a script, see [[AI_Relations_(Scripting)]]. Another method to switch AI teams using S&R (stim & response) is described here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__256126] and see the entry [[Stim/Response]].

'''Q. How do I make an AI play an animation when I want?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__253169]. There may be other ways possible.

'''Q. How do I set or change the health of AI?'''

'''A.''' AI use the spawnarg "health" to set their hit points. To change it in-game, use a script and the function "setHealth".

'''Q. How do I pose ragdolls so they look naturally placed?'''

'''A.''' Save a backup, pose all the ragdolls in-game, then use the console command saveRagdolls which saves their positions to the .map file. cf. [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__265650].

'''Q. How do I make a scene of AI playing cards?'''

'''A.''' Probably the easiest thing to do is load the prefab (under AI), place it, and adjust it how you want.

'''Q. How do I make an AI frob something?'''

'''A.''' To get an AI to frob something, eg, a lever (doesn't work to pick up and carry) create a path_interact entity. You can include it in a normal pathing patrol. Give it these 2 spawnargs: ent <name of entity you want the AI to frob>; target <next path entity (if any)>. Note that the AI won't walk to this entity; you have to use a path_corner to get him where you want then target to the path_interact to get him to frob.

'''Q. How do I make an AI catch fire?'''

'''A.''' You can bind some unlit fires to an NPC (like a zombie) and shoot it when a fire arrow, he'll erupt in flames, but the flames won't damage him. You could also light him with a candle. I'd bet theres some way to make that actually kill the creature, or at least cause it damage. ... One improvement suggestion: When the the light gets the fire stim, target a trigger multiple, which delays for a 120-240 seconds and then turns the fire off. You could make the fire damaging by starting a trigger timer which applies the stim damage to the target every few seconds. Remember to switch off the timer when the flames are doused.

'''Q. How do I keep an AI ragdoll from sinking into the bed model, e.g., if he's KO'd?'''

'''A.''' I found one way to keep [an unconscious/dead ragdoll body] from sinking into the model below it is to use a platform of nodraw_solid underneath the body. You should be able to place such a brush within the bed model and test it with a ragdoll on the bed. Adjust it's top surface height until the body lays just on top of the bed (then delete the ragdoll)... then a blackjacked AI should be able to stay on top of the bed like the ragdoll did.

== The Player ==

'''Q. How do I do things with the player's inventory, like trigger an inventory item to be deleted, or an item to be added to the inventory, or one item being replaced with another item?'''

'''A.''' You can do all these things with a script (read [[A_Beginner's_Guide_to_Scripting]] and the scripting FAQ below to learn about scripting). Have your triggering mechanism trigger a target_callscriptfunction entity which calls a custom script, then use the appropriate script command in the script on $player1. A list of the commands is here [[Inventory#Scriptsupport]].
Useful commands are (replacing the "Item" variables with the item ID):
* '''$player1.addInvItem(inv_item);''' and
* '''$player1.replaceInvItem(oldItem, newItem);''' (note: If <newItem> is the $null_entity, <oldItem> is just removed and no replacement happens.)
For example, to remove a key from the player's inventory, use a command like: '''$player1.replaceInvItem ($key, $null_entity);'''

'''Q. How do I teleport the player?'''

'''A.''' Use base > info_player_teleport. Give it the spawnarg and value: target info_player_start_1. Give it the spawnarg: angle with a value if you want to force the player to turn to face a particular direction.

'''Q. How can I simulate a crawl for the player to pass under things like tables that he couldn't normally do?'''

'''A.''' See this post [[http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__229174]]

== Scripting ==

'''Q. How do I make a custom script?'''

'''A.''' First read [[A_Beginner's_Guide_to_Scripting]], [[Scripting_basics]], and [[My_first_map_script]] to learn the basics of scripting. You write a custom script as a text file named <mapname>.script and packaged in your .pk4 in the same place as your .map file. Inside it you make your own script object or function (I'll just call them "scripts" from now on, since a "scriptobject" refers to a specific spawnarg in TDM, not the general case as I mean it here) in the format the Beginner's Guide gives you, usually looking like '''void MyScript() { code goes here }'''. Then the game can "call" "threads" of that script that will run until they end or are killed, so you can have more than one thread running of the same script concurrently. If you want multiple scripts, put them all in your <mapname>.script file and the game-engine will find them. You run scripts by the script name, not the file name.

'''Q. How do I run a script in-game?'''

'''A.''' A few common ways of calling a script thread in-game are
# creating a target_callscriptfunction entity with the spawnarg: "call" "<name of your script>", then creating some other entity (such as a button or trigger brush) that "targets" that entity;
# creating a button with the property "state_change_callback" "<script>", which runs the script when pushed or triggered,
# Using [[Location_Settings#Script_calls]] to call a script when you enter or leave a location;
# triggering a script with the [[Objectives_Editor]] when you fulfill or fail an objective (possibly a hidden objective only for triggering the script);
# A script can call another thread in itself with the "thread" function; see the command in the link below.
# An entity can call a script when it spawns. Add a property/value either in the .def file or as a spawnarg on the entity: "ScriptEvent void <script>(<parameters>);".
# The script "void main();" is always called at game start. So if you add code under that heading in your script file, it will run at game start.
There are other methods too. (Note, if you call a persistent script, i.e., it runs all game, be especially sure to avoid performance hits, or make it non-persistent if possible, that is, you "kill" it at some point in the game so it doesn't hog resources..)

'''Q. What are script events (aka commands or functions)?'''

'''A.''' A script event is a pre-made object or function that does something for you, usually to some game item you specify, just when you write it in your code (like '''$item.eventX();''' does X to item). Sometimes it wants parameters or arguments to run (the stuff in parentheses) and will give an error if you don't put the arguments in the parentheses in exactly the way it wants, with the right number of them & right data types, etc. And some of them return values too, especially the "get" functions, which are handed over to a variable (e.g., '''X = getValue();''', now X has the value. If X is an entity, you can even act on X as if it's the entity itself. Just be sure the data type of X and Value are the same, e.g. float, or string, or entity, etc, or you'll get an error).

'''Q. What are some common or useful script events for editing?'''

'''A.''' A list of all Doom3 and TDM script events are listed on this wiki page [[TDM_Script_Reference]], including the proper syntax (or this page, but it's down now: [http://www.modwiki.net/wiki/Script_events_%28Doom_3%29]), or also these two files in your Dark Mod folder (open with a text editor): scripts/doom_events.script, scripts/tdm_events.script. Note that TDM has some of its own script events, like setFrobable (in the tdm_events.script list).

A quick short list of common or useful script events good for editing is here: [[Script_Events_User-Friendly_List]], with syntax and description, and including TDM events. It doesn't list all script events and all details, just common & useful ones for actual mapping IMO. If you want the full list, use the TDM_Script_Reference link I gave above.

== World Building ==

'''Q. What's a good way to make caves?'''

'''A.''' Some tips are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__204909] & [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__289484] Instructions for quick-cavern pattern building is here [http://forums.thedarkmod.com/topic/14469-quick-caverns-recipe/page__view__findpost__p__304250]

'''Q. How do I make a good looking roof using clean brushwork, including with an attic inside?'''

'''A.''' Here are descriptions of method that all use a similar trick [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__325945], [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__325944], [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__244109]. The trick is to "cut out" a roof from a square brush using the clipper tool. Avoid rotating brushes to make it by hand. Alternatively, use patches over a rectangular under-structure of BSP brushes, although this is not good if you want a portaled attic.

'''Q. What's a good way for making a city area that performs well?'''

'''A.''' Sotha gave a good method in this post. [http://forums.thedarkmod.com/topic/10003-so-what-are-you-working-on-right-now/page__view__findpost__p__312133]

'''Q. What's a good way for making a forest or a big outdoorsy area?'''

'''A.''' One good method is making large "rooms" in the shape of a big oval cylinder with very high natural-looking "rocky" & skybox walls and uneven ground using patches, filling it with trees and hiding some of the walls behind trees and greenery (you could also fill it with thick cylinder brushes of different sizes with bark texture to look like more trees, and place branches coming off them or to make a canopy), and possibly filling it with tons of grass (using [[SEED]]) and rocks and streams, with visportaled openings at "kiss points" in the walls to other large oval rooms at different orientations (maybe 2-5 connections per oval) so there's a dense web of interconnected forested rooms that (sort of) appear to be one big dense forest to the player. Some useful things to use are the [[Object_detail]], [[SEED]], and [[LOD]] systems. See the blueprint for the Thief 2 level Trail of Blood for a rough idea: [http://thief.wikia.com/wiki/T2_M10_Trail_of_Blood?file=T2_m10a_editor_colored.gif]. For good examples in Dark Radiant, look at the construction of mission 3 of No Honor Among Thieves ("No Honor Among Anyone") and Shadowhide's slenderman forest map. (Somebody post links to screenshots of those maps in DR, or remind me to.)

'''Q. How do I make uneven ground?'''

'''A.''' One method is by burying patches into the ground that stick out and make the ground lumpy as described here [http://forums.thedarkmod.com/topic/13338-newbie-mapper-tip-making-uneven-ground/page__view__findpost__p__274917]. For more encompassing unevenness, you can use much larger patches laid over square caulk brushes underneath that seal the leaf to make the entire ground uneven.

'''Q. How do I make a natural looking road where there isn't a sharp seam between the road material and grass but a nice fading transition?'''

'''A.''' See the Wiki page for [[Roads]].

'''Q. How do I make curved ceilings and archways?'''

'''A.''' Use patches. Here's a list of some good tutorials for this sort of thing [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__254764]. Also look at this wiki page [[Patches#Archways]].

'''Q. What's a way to get good-looking fog in my mission?'''

'''A.''' There are numerous values to make good fog. The setup for the fog from Fidcal's Heart mission is here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__248277].

'''Q. What are some tips to making a better looking map?'''

'''A.''' See this wiki entry [[10_Simple_Tricks_for_Better_Looking_Maps]].

'''Q. What's a good method or plan-of-action for building?'''

'''A.''' This is a matter of personal preference, but a method that professionals use is called the "stepwise refinement" method. It means you build the *entire* space of your mission first in rough blocks (so you have it all planned out first), then refine the whole thing in increasingly more detailed steps section by section, leaving the most fine detailing towards the end. It can help to use DR's Layer system to organize your building by sections too, without other sections interfering. Also, when you're drawing your map, think about arranging space into winding "rooms" (so there's no long lines of sight), even outside with tunnels, walls and skybox; and think about visPortal placement right at the start. Also think about the gameplay-performance balance of shadowing-lights & AI when thinking about placing them.

'''Q. How do I cleanly connect two brush edges meeting together, especially at a diagonal?'''

'''A.''' See this post [[http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__257111]].

'''Q. What's a method for building very fast & efficiently?'''

'''A.''' Sotha came up with "modular" approach where you build a few stock modules of architecture that you can combine to make a lot of geometry very quickly and efficiently. Here's his description: [http://forums.thedarkmod.com/topic/12833-sir-taffsalots-mapping-thread/page__view__findpost__p__290747]

'''Q. How do I make a good looking waterfall?'''

'''A.''' There's a discussion about this in this thread [http://forums.thedarkmod.com/topic/11901-waterfalls/page__pid__303963#entry303963]. For a small waterfall, a white foamy particle effect raining down by itself looks good. You can copy Bikerdude's example from St. Alban's Cathedral. [http://www.youtube.com/watch?v=gIrZDpc1m68]. For a bigger waterfall, people talked about a combination of a flowing vertical water block with the foamy particle effect towards the bottom.

'''Q. How do I make a nice little pond.'''

'''A.''' See this wiki entry [[How_to_create_a_pond]]. This thread [http://forums.thedarkmod.com/topic/14647-how-can-i-make-a-realistic-looking-pond/page__view__findpost__p__308916] has discussion on it.

== Patches! ==

'''Q. Is it possible to split patches?'''

'''A.''' See this tutorial on it [[Patch_Splitting_-_Basic_Tutorial]].

'''Q. How do I bend patches?'''

'''A.''' See the instructions at [[Patches#Bending_Patches.2C_Curves.2C_L-shapes.2C_etc]] (Here's another small tutorial in a post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__277350].)

'''Q. I want to use a patch to round off a corner.'''

'''A.''' See this part of the Patch wiki page [[Patches#Round_and_Soft]].

'''Q. How can I make a perfect circle with patches?'''

'''A.''' Select verts of 4 corners, select the "rotate and scale" tool, and use the value "0.9428" to scale "up" (actually down) in the 2 corresponding axis of the scale tool. See this post [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__279356].

'''Q. How do I make a dome or sphere?'''

'''A.''' Make a cone patch and drag down the top vertex to form a dome. Invert the matrix if you want an internal dome or thicken if you want it to be visible inside and out. A sphere is just two of these stuck together. Also tweak the tesselation in patch inspector if it is too chunky. You can have fun with the textures though; try fit. If you totally flatten the dome you have a disc which can produce some nice texture effects, eg, the marble floor centrepiece or a round rug. Drag a side to make it oval. See this post for a picture [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__233107].

'''Q. How do you align a texture on a curved patch?'''

'''A.''' When you want to align properly texture to curved patch like this one in the image [NB: image is missing], divide a brush according to the angle of the patch then use it's shader for your purpose. ... I made it with one edge is at one end of the curved patch and the other edge is at the other end. It gets distortions without this way.

== Events and SFX ==

'''Q. How do I trigger an earthquake event?'''

'''A.''' Earthquakes can be done with a speaker. Just use the spawnarg "s_shakes" "1" on the speaker, and the screen will shake violently however loud the sound gets.

'''Q. How do I emulate something like a blizzard or dust storm?'''

'''A.''' Doom3 made a dust storm area, and the same method can be used to make a blizzard, so it's possible. I'm leaving this here to look up instructions for future reference.

'''Q. How do I make the screen fade to black (or some other color), or from black back to the game.'''

'''A.''' Create entity: [[Triggers#trigger_fade|Trigger_Fade]]. Adjust "fadeTime" and "fadeColor" spawnargs as desired.

== Textures ==

'''Q. What's a quick way to align textures between two surfaces?'''

'''A.''' For two brushes, select the first surface, then '''edit --> copy shader''', then click on the second surface and '''edit --> paste shader'''. This will seamlessly match the 2nd surface to the texture of the 1st. DR also comes with a useful tool for texture alignment, [[Texture_Tool]], which you bring up with Ctrl+Alt+T. If it's textures on two patches, you can follow these directions: [http://forums.thedarkmod.com/topic/14034-tutorial-for-road-creation/page__view__findpost__p__294114]

'''Q. How do I randomize the position of textures on multiple brushes, e.g., for a row of stairs or pillars all with the same texture that I want to look different?'''

'''A.''' Select multiple faces and in the surface inspector, press the natural button once you set the scale properly.

'''Q. Can I blend textures?'''

'''A.''' Yes. This is particularly good for dirtying some textures up by blending in a grime texture. You can blend textures with a custom material file. Link to instructions coming. Also see the entry for [[Basic_Material_File]].

'''Q. How about blending texture transitions so there isn't a sharp seam, e.g., for a dirt path in grass?'''

'''A1.''' DR comes with grass edge transition decal patches to overlay the hard edges. Read how to set it up here [[Grass_Edges]], or a more detailed tutorial on making roads here [[Roads]].

'''A2.''' In NHAT blended terrain was made from patches broken into segments then exported as ASE models. Then the models were vertex painted in Blender and imported back into Dark Radiant. See this tutorial [[DrVertexBlend_(tutorial)]].

'''Q. How do I set the color for some textures (like glowing mushrooms) and make lightbulbs go dark when turned off?

'''A.''' "Colorme" textures allow you to set the color with a spawnarg. So e.g. for colored mushrooms, choose a colorme skin with the spawnarg like "skin" "mushroom_selflit_green_colorme" and choose the color with a spawnarg like "_color" "0.24 0.50 0.40" (where the value is the RGB values you want). For lightbulbs you can trigger a colorme texture switch with the lightswitch (so it switches between "lit up" and "black"). Instructions on that coming.

'''Q. What's a fast way to put different textures on a lot of objects?'''

'''A.''' 1. Click the mouse wheel on the texture to copy it. 2. To paste it naturally (i.e., in a random position): shift+mousewheel click. 3. To just paste it: ctrl+mousewheel click.

'''Q. Can you tile a texture a specific number of times to fit a surface?'''

'''A.''' When you want to tile a texture a certain number of times, enter the values 1/X and 1/Y (you need to compute them in your head) in the little boxes in the surface inspector, then press "Fit". It will tile your texture horizontally X times and vertically Y times. You can also enter things like "2" and "1" and get a texture that only occupies half of the width. You can then use the "Right" or "Left" buttons to align it quickly at the ends. Pro-tip: Press CTRL+ALT+T to open the texture tool, it allows super quick aligning of textures on patches. Esp. useful for decals where the decal texture consists of multiple decals.

== Readables & GUIs ==

'''Q. How do I put custom art in a book or scroll, like a picture?'''

'''A.''' Use a custom .gui. Here's a rough idea to get you started [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__263836]. I'll try to put better instructions in later.

'''Q. How do I trigger a text message to pop up and say something?'''

'''A.''' Create an entity: darkmod > targets > atdm:gui_message and give it the properties/values that you want. Popups will explain each one. You can target it with a triggering entity or trigger it from a script or any other triggering mechanism. An example is here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__256592]

== Lighting and Sound ==

'''Q. How do I add music or ambient sounds?''' '''Q. Can I dynamically adjust the ambient lighting?'''

'''A.''' For both of these things, check out the article for [[Location Settings]]

{{editing|sort=Editing FAQ (Troubleshooting & How-To)}} {{tutorial-editing|sort=Editing FAQ (Troubleshooting & How-To)}} {{darkradiant|sort=Editing FAQ (Troubleshooting & How-To)}}

'''Q. How do I set up Reverb (EAX) settings for my rooms? (E.g., the echo of a large hall, etc.)'''

'''A.''' Create a text file and name it <mapname>.eax; place it in your .pk4 with your .map file; and in it create entries by location name with the values you want for that location. See this wiki entry to see the format & values [[Setting_Reverb_Data_of_Rooms_(EAX)]].

Unofficial Tweaks

2013-12-01T02:23:00Z

Demagogue:

Fans sometimes make unofficial tweaks to the game that change some aspect to their personal preference or to try interesting things. These tweaks aren't supported by the team or even necessarily recommended; they may have issues or go out of date with new versions; and there aren't plans to implement them in the official game. But in case other fans may be interested, or for educational purposes, some of them or instructions for them are collected here. If there are issues or questions, the person to talk to would be the original creator.

* Smaller light gem size: [http://forums.thedarkmod.com/topic/15346-smaller-hud/page__view__findpost__p__325993]

* Pain wheel (A HUD gui that tells you the direction of damage): [http://forums.thedarkmod.com/topic/15633-implementing-a-pain-wheel/page__view__findpost__p__327673]

Unofficial Tweaks

2013-11-10T02:23:08Z

Demagogue:

Fans sometimes make unofficial tweaks to the game that change some aspect to their personal preference. These tweaks aren't supported by the team or even necessarily recommended; they may by buggy or out of date with new versions; and there aren't plans to implement them in the official game. But in case other fans may be interested, or for educational purposes, some of them or instructions for them are collected here.

* Smaller light gem size: [http://forums.thedarkmod.com/topic/15346-smaller-hud/page__view__findpost__p__325993]

Unofficial Tweaks

2013-11-10T01:40:19Z

Demagogue: Created page with "Fans sometimes make unofficial tweaks to the game that change some aspect to their personal preference. These tweaks aren't supported by the team or even necessarily recommend..."

Fans sometimes make unofficial tweaks to the game that change some aspect to their personal preference. These tweaks aren't supported by the team or even necessarily recommended; they may by buggy or out of date with new versions; and there aren't plans to implement them in the official game. But in case other fans may be interested, some of them or instructions for them are collected here.

* Smaller light gem size: [http://forums.thedarkmod.com/topic/15346-smaller-hud/page__view__findpost__p__325993]

Editing FAQ - Troubleshooting & How-To

2013-11-09T01:13:54Z

Demagogue: /* Performance Issues */

Below are some common issues and questions mappers have had in the Editor's Guild forum with common solutions. Some of this assumes you've already gone through the [[A_-_Z_Beginner_Full_Guide_Start_Here!]], [[Startpack_Mappers'_Guide]], and [[Dark_Radiant_Must_Know_Basic_Intro]]. (If you know a FAQ not here and worth going in this list, and you know the right answer(!), or you can improve an existing answer, please add it if you have edit control or PM it to a team-member if you don't.)

= Troubleshooting FAQ =

== Rendering & VisPortal Issues ==

'''Q. Some of my brushes have disappeared or turned black and won't render.'''

'''A.''' This can happen when two touching brushes around the seam are not perfectly flush with one another and the rendering hiccups for those brushes & brushes behind it, either there's a tiny wedge or overlap or gap or weird angle between them. The usual solution is to make sure the brushes are snapped to the grid and perfectly flush against one another, or more generally to simplify the brushwork around the seam of the disappearing brushes.

'''Q. My visportal is not showing up or not closing like it should (you can check this with by typing "r_showportals 1" in the console. The portal edge will show green when open and red when closed.).'''

'''A.''' A common reason for that is that the two areas separated by the portal are not hermetically sealed and there's an internal leak, either (1) there may be an unportaled gap between the two, possibly covered up by func_static (which do not seal) or possibly caused by an inadvertent hole created by the first FAQ question above, or (2) an internal leak can happen when all sides of the visportal are not buried in or flush against sealing brushes, and there's a gap between the visportal and brush, or possibly even a tiny gap just touching the visportal side is enough to break it. A way to check if there's an internal leak, and locating it if there is, is described here: [[Visportals#Trouble-shooting]]. Other reasons it might fail are also described there (such as accidentally changing a nodraw texture to something else).

'''Q. I can see other rooms behind a mirror (or any reflective surface) through it, instead of just a reflection.'''

'''A.''' The area behind a mirror should be in a separate leaf (visportaled area) behind a closed visportal so it doesn't render. This problem usually means the two areas aren't in separate leafs, the portal isn't closed, or there's an internal leak between the areas in front of and behind the mirror.

'''Q. Help! I'm having rendering & visPortal issues all over the place ... broken portals, sparkly lines, disappearing brushes, z-fighting, uneven walls, etc.'''

'''A.''' As a general piece of advice, messy brushwork leads to trouble one way or another. To keep your brushwork clean:
* keep snapped to the grid (Ctrl+G toggles) & stay away from small grid levels (Typing a number or Plus/Minus changes the grid scale; 8 is a good starting grid; staying at or above 2 or 4 is fine for most stuff; going below 1 is usually just for special situations).
* Make brush intersections perfectly flush.
* Stay away from unnecessary tiny brushes & wedges (leave detail work to func_statics; brushes are for closing off leafs and the void. Of course you can do fine detail work with brushes & convert them to a func_static).
* Don't use the "CGS Subtract" tool if it will shatter the brush into tiny slivers; use the cut tool instead (open by pushing "X").
* You can use patches for uneven geometry with square brushes underneath textured with caulk.
* When rotating geometry, avoid weird angles when you can (where vertexes end up off the grid), and for multi-brush structures, build the whole thing first *then* rotate it all together instead of rotating & placing each brush individually.
These aren't rules set in concrete if you want to do something special once in a while, but general rules of thumb that will make life a lot easier if you generally stick to them.

== Crashes and Warnings ==

'''Q. My map has a leak in it, but a pointfile either isn't generated or doesn't make sense. (A pointfile is generated when dmap occurs and there's a leak, then you open DarkRadient and click File>Pointfile to see it. It normally runs a red line that ends in the void, pointing out the leak).'''

'''A.''' Make sure a gap isn't covered up with func_statics. If the origin of a model is in the void it will also cause a leak with a non-sense pointfile. Read more on the [[Leaking maps]] page.

'''Q. How do I scroll up through the console output to see what a problem was during dmap or map or in-game?'''

'''A.''' Use the mouse wheel or PageUp/Down to scroll through the console.

'''Q. I'm getting an error message "warning: aas is out of date" once my map has loaded. What does it mean and what do I do?'''

'''A.''' The AAS is for AI pathfinding. It usually means you changed brushwork and started a map without dmapping first. The solution is to dmap. If you dmap and still get the warning, delete your .aasxx, .proc, and .cm files in the maps folder and dmap again. If you're still getting a warning, then it could be a sign that something in your map is breaking the AAS pathfinding. Try monsterclipping tricky areas for the AI to path (like around objects and uneven ground) or clean up messy brushwork that might break the dmapping like sliver brushes.

'''Q. I have encountered a malloc failure error while dmapping my level. Instead of finishing with the dmap operation, it crashes midway with an error message.'''

'''A1.''' One solution to this is given in the Dmap wiki entry here: [[Dmap#Malloc_Errors]].

'''A2.''' This is what I've done to fix this exact issue. Open the map in DarkRadiant, select everything, copy to clipboard. Open another instance of DarkRadiant and paste from clipboard. Save as new filename and dmap new file and that has worked 3 times now with random unresolvable crashes.

'''A3.''' GC and I have found correlations between visportalling and mAlloc errors. Time to re-arrange your visportals. In NHAT, we had many malloc problems until we retooled how each area was portaled. Originally, every other visleaf had tons of entities, while half had hardly any. That's not neccessarily bad, but it strains the dmapper when one or two visleafs are cluttered with entities that really bloat your mapname.proc file. We added a few more portals to even out entity distribution, and dmap was happy again.

== Performance Issues ==

'''Q. My map is so slow. How do I improve performance?'''

'''A.''' See these wiki entry: [[Performance:_Essential_Must-Knows]]. Tips include:
* Reduce AI [[Pathfinding]] with Monsterclipping helps performance, simplifying complex bumpy surfaces into 1 smooth monsterclipped surface (or raise the monsterclip height to be inside the ceiling and there is no pathfinding computation at all), or excluding entire surfaces AI should never walk on, like detail brushwork or some roofs.
* Use [[Interleaved_Thinking_optimization]]. Reducing AI think-time helps performance quite a bit.
* break-up long lines of sight,
* improve visportal & leaf placement (so less architecture is rendered at a time),
* use fewer AI,
* convert ornamental brushwork into func_static,
* reduce the overlap of light sources on surfaces by adjusting their placement & reducing their light-radius. (Every time a new light hits a surface, it's another render pass. So 4 lights hitting a surface processes it 4 times. If only 1 light hit it, its lighting is processed in 1/4 the time), and
* set objects and lights to "noshadow" if it won't be noticable to the player or affect gameplay (possibly in combination with low-poly shadow meshes or shadowy decals. Note that "noshadow" has two jobs. Put on lights, it means that light will cast no shadows on any object. Put on objects, it means that object will not cast a shadow from any light.)

There are also lots of other tricks out there if you check around the forums, including more advanced & optional tricks such as using the [[LOD]] system or [[SEED]] system, or even crazier tricks (cross-leaf func_statics, skybox architecture, Strombine lighting, Camera Cubemapped Visportal Patches, lots of crazy tricks out there), that you don't have to worry about if you're a new mapper but you can ask us about or search for in the forum if you're curious. Generally speaking there are pros and cons trade-offs between performance & dazzle for many things (like lights or visportal placement); so it's good to think about the best performance-dazzle balance for your scene. E.g, lots of highpoly brushwork, lights, & AI can look good in a small or medium room, but may not be worth the performance hit in a big courtyard, and try to find ways to get better performance "for free" without the player noticing anything missing, like smart use of noshadows, monsterclips, and interleaved thinking distances.

== Gameplay Issues that Mappers sometimes Overlook ==

'''Below is a list of common gameplay issues that players sometimes complain about and that mappers & testers sometimes overlook or should at least be aware of.'''

- Players find it very difficult to frob objects (loot, keys, readables) when the frob distance is set too short or the space is awkward (like in a drawer or up on a wall, etc). In testing, please double-check that every frobable object is easy to frob from a comfortable place, and increase the frob distance if it's not, erring on the side of more space. (See the question on making frobbing easier under "Handling Objects" below for more information.)

- Objects can get stuck into brushwork while moving them around.

- Players can get stuck in narrow spaces and can't mantle out, so try to avoid this kind of geometry if possible.

- A very low ceiling can prevent hitting AI with a BJ, so try to avoid it when AI are around.

- Make sure AI have a flee path.

- Some players would like the ability to drop used keys and other inventory items, done by turning the can_be_dropped property to true, unless for gameplay reasons you don't want to.

- Some players don't like long readables that don't get to the point. At least be conscious of how your readables read to a player.

- Think about how you want to handle non-functioning doors (or other "unnatural" situations like windows that can open) in a way that visually or fairly communicates to the player that something is special about this door or window, but isn't too immersion breaking either.

== Issues with Objects ==

'''Q. My streetlight, candle, lamp, light-creating object, causes a weird shadow I want to get rid of.'''

'''A.''' Put the spawnarg "noshadows" "1" on the offending object.

== AI Issues ==

'''Q. My AI will not pass through a visportal no matter how I set up the path nodes.'''

'''A.''' Check that the sides of the visportal use the nodraw texture (except for the portal-face itself of course).

'''Q. How do you get AI to walk on complex terrain patches or func_statics?'''

'''A.''' You can always lay down invisible monsterclip brushes and the AI can walk on it. Overlay with a brush with a "material" clip texture so it causes the right sound for footsteps.'''

== Problems with Patches ==

'''Q. I have 2 curved patches and they're not aligning. What do I do?'''

'''A.''' See this wiki page [[Patch_Troubleshooter]].

'''Q. My patch is rendering strangely, like fractured into slivers.'''

'''A.''' See this wiki page [[Patch_Troubleshooter]].

== Issues with Lighting & Sound ==

'''Q. Some of the parallel lights I use for moonlight aren't giving off any light.'''

'''A.''' This is a known problem with parallel lights. For some reason in some arrangements you get no light at all. Just fiddle with it a bit - move it slightly, change the radii, move the vertex a bit - and it should suddenly work. Once you've got it working then it's stable. Likely the code chokes on certain values in its calculations. ... Also, to help optimize your moonlight, you should adjust the radius so it's only as big as it needs to be. You may also want to move the actual position of the little moon cube in the skybox to match the parallel light (and make sure to fix the texture on it if you mess it up - hint: lock textures before moving cube to make it easy)

= General How-To Editing FAQ =

== Dark Radient Questions ==

'''Q. How do I see all the default properties already on an object?'''

'''A.''' In the entity inspector there's a checkbox near the top that says "Show Inherited Properties". Click that box.

'''Q. What are some basic units, scales, limits, maxs, and mins of various things when editing?'''

'''A.''' A list of all these things is here: [[Limits,_Max,_Min,_Stats,_etc]].

'''Q. Can I manipulate brushes to resize and reshape them?'''

'''A.''' Yes. In DarkRadient you can select a brush and push "V" to select verticies to drag and resize, "E" to select edge(s) to drag and resize, and "F" to select face(s) to drag and resize. "Ctrl+#" makes a selected brush be #-sided. You can also use the Brush>Prism and Brush>Cone to convert a brush to those shapes.

'''Q. What are some common DR shortcut commands?'''

'''A.'''
* "H" hides selected items.
* "I" inverts selected.
* "Ctrl+I" inverts a patch's normal.
* "J" brings up entity list.
* "Ctrl+K" makes 1st-selected-entity "target" 2nd-selected-entity.
* "L" brings up light inspector.
* "Ctrl+L" brings up the Layers menu.
* "N" brings up entity inspector.
* "T" brings up texture browser.
* "X" go into clipper mode.
* Brush manipulation modes: are "R" rotate brush, "Q" free-move & resize, "W" translate-move.

'''Q. How do I make my own shortcut key commands?'''

'''A.''' Under the Edit menu, at the bottom is "Keyboard Shortcuts" which allows you to set your own shortcuts.

'''Q. I screwed something up! What do I do?!'''

'''A.''' Ctrl+Z undos. Ctrl+Y redos.

'''Q. Is there a way to organize & simplify building, so I can build one section at a time without other sections getting in the way?'''

'''A.''' DR has a [[Layers]] function that lets you build one "layer" at a time (open with ctrl+L or View>Layers). It also improves DR performance, which is handy as the map gets bigger.

'''Q. How do I set up things like the pre-game shop, the player inventory, and an in-game map?'''

'''A.''' All these things are described in the Startpack Mappers' Guide: [[Startpack_Mappers'_Guide#Ammo.2C_Weapons.2C_Player_Tools.2C_Start_Inventory]], [[Startpack_Mappers'_Guide#Purchase_Shop]], [[Startpack_Mappers'_Guide#Adding_an_In-game_Map_to_your_FM]]

'''Q. How do I put spawnargs on def_attached entities?'''

'''A.''' You can put spawnargs on def_attached entities by using the spawnarg "set SPAWNARGNAME on ATTACHMENTNAME" "value" on the base entity. Here's an example of setting a color property on a flame attachment to a torch "set _color on flame" "0.2 0.2 0.9". Read more here [[Combined_light_entities#Setting_spawnargs]].

'''Q. What's an easy way to find materials in DR?'''

'''A.''' Tip to help find materials in Dark Radiant's materials browser:
# Point to Textures (or any tree).
# Shift + Right key to fully open the tree.
# Type the key letters of what you want to find.
# Up/down arrows to go to next/previous occurrence.
# Esc to get out of input field.
Oh yeah, avoid F3 because that is likely to switch to render mode which in my case crashes DR (but may not if the map is small).

'''Q. How do I make an N-sided brush?'''

'''A.''' A quick way to make an N-sided brush is to highlight the brush and push cntl+N (N being the number of sides for the top face). So if you want a 5-sided brush, highlight it and push cntl+5. But the best way to get the walls of a multi-sided brush to line up seamlessly is still to use the clipper-tool and precisely cut off a slice. (And don't use CSG Subtract unless you know what you're doing and aren't creating a million splinters!)

== Console Questions ==

'''Q. How do I open the console?'''

'''A.''' Open the console with ctrl+alt+~ in a normal game, and just ~ when playing through "map".

'''Q. How do I scroll through the console output?'''

'''A.''' Use the mouse wheel or PageUp/PageDown.

'''Q.What's a list of all the Doom3 Console Commands and CVars?'''

'''A.''' A list of all commands & Cvars is here [http://www.doomwadstation.com/doom3/console/]. Darkmod Cvars are listed here [[Cvars_in_The_Dark_Mod]].

'''Q. What are some *useful* console commands and cvars for editing?'''

'''A.''' Here's one list: [[Console_Useful_Controls]]. Here's a list more tailored to mapping:

Commands:
"'''dmap <name>'''" compiles a map,
"'''give <name>'''" gives the player an item,
"'''god'''" player cannot be harmed,
"'''killmonsters'''" takes out all AI
"'''map <name>'''" loads a map to play,
"'''noclip'''" lets the player go through objects and walls,
"'''notarget'''" let's the player be invisible to AI,
"'''reloadDecls'''" will reload material defs without having to re-start TDM,
"'''reloadimages'''" does the same for lights and
"'''reloadSurface'''" for surfaces,
"'''saveRagdolls'''" saves the positions of all ragdolls to the .map file (see the FAQ under Handling AI),
"'''teleport <name>'''" teleports the player to an entity.
"'''tdm_show_loot'''" Shows loot.
"'''spawn <name>'''" spawns an entity:
spawn atdm:weapon_blackjack
spawn atdm:weapon_shortsword
spawn atdm:ammo_broadhead
spawn atdm:ammo_firearrow
spawn atdm:ammo_gasarrow
spawn atdm:ammo_mossarrow
spawn atdm:ammo_noisemaker
spawn atdm:ammo_ropearrow
spawn atdm:ammo_waterarrow
Append "inv_ammo_amount 50" to any of the above to spawn 50 arrows at once: spawn atdm:ammo_broadhead inv_ammo_amount 50
Cvars (1 turns on, 0 turns off, unless otherwise noted):
"'''com_showFPS 1'''",
"'''r_showLightCount 1'''" (colors shows the number of lights hitting a surface, black = 0, red = 1, blue = 2... etc),
"'''r_showPortals 1'''" (red=closed,green=open) If your portals dont show up they are most likely not sealing.
"'''r_showTris n'''" (n=1) Shows tris rendered directly, (n=2) shows overdrawn tri's, (n=3) shows all tri's, direct and indirect.

== Objectives ==

'''Q. How do I set up a put-object-here objective?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__182924]

'''Q. How do I set up a "ghosting" objective (e.g., you are busted if you are seen.)'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__204695]

== Handling Objects ==

'''Q. How do I attach a door handle to a door?'''

'''A.''' Just position the handle and input "bind" and the door entity ID/name as a spawnarg.

'''Q. How do I make an object into loot?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__182921]

'''Q. How do I make an entity frobable?'''

'''A.''' See the entry for [[Making an Entity frobable]].

'''Q. Ok it's frobable, but doesn't fall or move. How do I make an entity act like a world object?'''

'''A.''' You need to make the object a moveable, see [[Moveables]].

'''Q. How do I get a lever or button to open a door?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__212036]

'''Q. How do I put some text on a sign or wall?'''

'''A.''' You can use this method [http://forums.thedarkmod.com/topic/11159-add-text-to-your-signs-signposts-walls-etc/]

'''Q. How do I bind something to a rope (like a body) so it doesn't fall?'''

'''A.''' Dynamic ropes are unreliable, so it's good to use a func_static like a chain or make a func_static rope from a cylinder brush. For a ragdoll, place the ragdoll so he clips into the func_static. You need to bind the ragdoll to the chain (so the spawnarg is on the ragdoll), with "bind" "func_static_...", where func_static_... is the chain. Or, through DR, you can just select the entity you want to attach (the ragdoll), then also select the thing you want to attach it to (the chain), and in the menus select "Entity" - "Bind selected entities". But it's been reported the clipping does the job, not binding. See this link [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__221262]

'''Q. How do I make something switch from frobable to unfrobable like a used lever, or unfrobable to frobable like contents in a chest or drawer you don't want frobable until it's open?'''

'''A.''' Make a brush around the object with a clip texture and convert it to an atdm:target_set_frobable entity, with the property "start_frobable" 1 or 0 (which mean true or false) depending on your case (it affects everything inside), and a triggering entity, such as the lever or the chest itself, that targets the set_frobable entity that triggers the switch when it's frobbed. For the record, you can also switch the frobability of an object in a script with the command: '''$<entityname>.setFrobable(n);''', where n is "1" to make it frobable and "0" for unfrobable.

'''Q. How do I make breakable glass?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__222734]. You basically convert your glass brush to a func_fracture entity and set the "health" spawnarg to the value you want the glass to break at.

'''Q. What about an object that gets increasingly damaged-looking as you hit it?'''

'''A.''' Use a func_damagable entity, which replaces its model and/or shader with increasingly "damaged" versions (as many stages as you like) when its health goes below the threshold you set with the "health" spawnarg, and you can use "target" to trigger something when damage occurs (such as a sound effect or event). See here for details on the spawnargs involved in setting it up: [http://www.modwiki.net/wiki/Func_damagable_(entity)]

'''Q. How do I make an object that you can frob and it does something or something happens?'''

'''A.''' If it's an object you made from patches or brushes, make it into a frobable func_static, or if it's already a func_static, make sure it's frobable ([[Making an Entity frobable]]). Then give it a Frob response whose effect is a trigger, and give it a "target" spawnarg to the entity that causes your effect when triggered.

'''Q. Can a lever or button target multiple entities?'''

'''A.''' Yes! Use the spawnargs "target1", "target2", "target3", etc, with each entity-target as a value. A quicker way is to use the keyboard shortcut Ctrl+K. Select the button or lever, then select the target-entity and hit Ctrl+K. De-select the target-entity then select the next one, hit Ctrl+K again. Each time adds a new target to the switch. (Many other spawnargs allow you to have multiple entries by numbering them, such as bind and def_attach.)

'''Q. How do I make a rotating entity, like a fan?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__242385]

'''Q. How do I make objects non-solid so they still render but the player can walk through them?'''

'''A.''' Add the spawnarg: noclipmodel 1 to turn them into non-solids.

'''Q. How do I make a firefly or will-o-wisp, basically a glowing ball that floats around?'''

'''A.''' This is a rough explanation to help you get started. A firefly is a func_emitter. Click the model property then use the button bottom right to select a suitable particle effect, possibly tdm_glare_lamp_01.prt. Bind to something invisible that will move it along a path, typically a func_mover with nurb curves used as the path. A tutorial for setting up nurb curves is here [http://www.doom3world.org/phpbb2/viewtopic.php?t=5123].

'''Q. How do I trigger an event from something in the player's inventory?'''

'''A.''' give the object a "target" to trigger and also the property/value: scriptobject InvTriggerScript. If your object does not already go in the inventory then use the entity: items > custom > atdm:moveable_custom_item. If you get a collision model error then ask on the forums for help (or read the wiki entry for [[Moveables]]).

'''Q. How do I teleport an entity?'''

'''A.''' Use targets/atdm:teleport. See this wiki page [[Teleporting_entities]].

'''Q. How do I make a custom inventory item with its own inventory icon graphic?'''

'''A.''' See this entry [[A_-_Z_Beginner_Full_Guide_Page_6#Special_Items]] for setting the inventory category, loot type, inventory name and inventory icon. To repeat the instructions for a custom icon: on the object put the property "inv_icon" with a value "guis/assets/hud/inventory_icons/<name>.tga" (substitute whatever name you gave it for <name>), and package your .pk4 to put your image file in that relative location. You can also see other inventory_icons there and can use an existing one, or package your .pk4 to replace an existing one with your custom one. A method for making an inventory icon is described here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__259172] (be sure to use an alpha channel to make the background transparent, tutorial: [http://www.axialis.com/tutorials/tutorial-misc001.html]).

'''Q. How do make an object that's hard to frob easier to frob?'''

'''A.''' One easy way is to add this property: frobbox_size 5. If it's still hard, see this post for other things you can do. [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__228245]

'''Q. How do I make a candle you can pinch to go out?'''

'''A.''' I made a bunch of pinchable non-moveable candles into my WIP like this:
# Make a func_static candlestick. place light source entity candleflame on it.
# Give the candlestick "frobable 1."
# Give the candlestick S&R response frob, extinguish light and candleflame name.
# You can optionally add another response frob to trigger a speaker with a "snuff" sound effect.
# Done.
You can copy the entity bunch around and all the params should update correctly for the new replica. Frobbing will not relight it: the player needs to relit them with a flame source.

== Handling AI ==

'''Q. How do I make sure a guard can unlock a door?'''

'''A.''' There are a few different ways, explained here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__217915]

'''Q. How do I attach a key or purse to an AI's belt, or similar kinds of attachments?'''

'''A.''' The easiest way is with "bind". Place the key or purse around the belt area where you want it, sticking a little farther out than usual, and rotate it as desired. On the key add the property "bind" with the value of the AI's entity-ID or name, then the property "bindToJoint" with the value "leftHips_dummy" or "rightHips_dummy" as needed. For attaching things in other places (like a ring or hat or necklace), it's the same general principle but you should look up the joint to attach to. A list of all the joint names is here: [[BindToJoint]]. See this wiki entry for more info [[Attaching_Items]]. For another method using def_attach see [[Attaching_Props_to_AI]], and this post for an example of the spawnargs involved [http://forums.thedarkmod.com/topic/13084-ai-attach-keys/page__view__findpost__p__276064]. The issue with def_attach is that the attached thing spawns at its own rotation angle, which might not look great and is tricky to change (if you insist, see [[AI_Attachment_Ingame_Editing]] and [[Cvars_in_The_Dark_Mod#Attachment_related]]). With bind you just place and "bind", and it stays where you put it.

'''Q. What about other kinds of attachments where special animations are involved, like torches and weapons?'''

'''A.''' For these you want to use Def_Attach. See this wiki entry [[Attaching_Props_to_AI]]. For heads & weapons specifically see this wiki entry [[Adding_Heads_and_Weapons_to_AI]]. (You can set spawnargs on the def_attached entities with the method described here [[Combined_light_entities#Setting_spawnargs]].)

'''Q. How do I mute an AI?'''

'''A.''' Give the AI the spawnarg: def_vocal_set atdm:ai_vocal_set_mute. If you only want to mute some barks, you'll have to modify the AI's .def file by hand, taking or commenting out the barks you don't want, and packaging the new def file in your mission's pk4. For coughing and animation based barks, see this post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__224558]

'''Q. Can I hide an AI until I trigger him?'''

'''A.''' No, the spawnarg "hide" doesn't work well with AI (they're made invisible, but still audibly there). Put the AI in a blueroom and use a teleport instead, or a teleporting script command. See the wiki entry for [[Teleporting_entities]]. Note, after teleporting an AI, pathing becomes a problem for it. See this post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__280818] and the previous posts on this issue to make sure the AI can path properly after a teleport.

'''Q. How do I manage AI teams, who is a friend, enemy and neutral?'''

'''A.''' To set the teams, see [[Relations]]. If you want to trigger a change in team with a script, see [[AI_Relations_(Scripting)]]. Another method to switch AI teams using S&R (stim & response) is described here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__256126] and see the entry [[Stim/Response]].

'''Q. How do I make an AI play an animation when I want?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__253169]. There may be other ways possible.

'''Q. How do I set or change the health of AI?'''

'''A.''' AI use the spawnarg "health" to set their hit points. To change it in-game, use a script and the function "setHealth".

'''Q. How do I pose ragdolls so they look naturally placed?'''

'''A.''' Save a backup, pose all the ragdolls in-game, then use the console command saveRagdolls which saves their positions to the .map file. cf. [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__265650].

'''Q. How do I make a scene of AI playing cards?'''

'''A.''' Probably the easiest thing to do is load the prefab (under AI), place it, and adjust it how you want.

'''Q. How do I make an AI frob something?'''

'''A.''' To get an AI to frob something, eg, a lever (doesn't work to pick up and carry) create a path_interact entity. You can include it in a normal pathing patrol. Give it these 2 spawnargs: ent <name of entity you want the AI to frob>; target <next path entity (if any)>. Note that the AI won't walk to this entity; you have to use a path_corner to get him where you want then target to the path_interact to get him to frob.

'''Q. How do I make an AI catch fire?'''

'''A.''' You can bind some unlit fires to an NPC (like a zombie) and shoot it when a fire arrow, he'll erupt in flames, but the flames won't damage him. You could also light him with a candle. I'd bet theres some way to make that actually kill the creature, or at least cause it damage. ... One improvement suggestion: When the the light gets the fire stim, target a trigger multiple, which delays for a 120-240 seconds and then turns the fire off. You could make the fire damaging by starting a trigger timer which applies the stim damage to the target every few seconds. Remember to switch off the timer when the flames are doused.

'''Q. How do I keep an AI ragdoll from sinking into the bed model, e.g., if he's KO'd?'''

'''A.''' I found one way to keep [an unconscious/dead ragdoll body] from sinking into the model below it is to use a platform of nodraw_solid underneath the body. You should be able to place such a brush within the bed model and test it with a ragdoll on the bed. Adjust it's top surface height until the body lays just on top of the bed (then delete the ragdoll)... then a blackjacked AI should be able to stay on top of the bed like the ragdoll did.

== The Player ==

'''Q. How do I do things with the player's inventory, like trigger an inventory item to be deleted, or an item to be added to the inventory, or one item being replaced with another item?'''

'''A.''' You can do all these things with a script (read [[A_Beginner's_Guide_to_Scripting]] and the scripting FAQ below to learn about scripting). Have your triggering mechanism trigger a target_callscriptfunction entity which calls a custom script, then use the appropriate script command in the script on $player1. A list of the commands is here [[Inventory#Scriptsupport]].
Useful commands are (replacing the "Item" variables with the item ID):
* '''$player1.addInvItem(inv_item);''' and
* '''$player1.replaceInvItem(oldItem, newItem);''' (note: If <newItem> is the $null_entity, <oldItem> is just removed and no replacement happens.)
For example, to remove a key from the player's inventory, use a command like: '''$player1.replaceInvItem ($key, $null_entity);'''

'''Q. How do I teleport the player?'''

'''A.''' Use base > info_player_teleport. Give it the spawnarg and value: target info_player_start_1. Give it the spawnarg: angle with a value if you want to force the player to turn to face a particular direction.

'''Q. How can I simulate a crawl for the player to pass under things like tables that he couldn't normally do?'''

'''A.''' See this post [[http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__229174]]

== Scripting ==

'''Q. How do I make a custom script?'''

'''A.''' First read [[A_Beginner's_Guide_to_Scripting]], [[Scripting_basics]], and [[My_first_map_script]] to learn the basics of scripting. You write a custom script as a text file named <mapname>.script and packaged in your .pk4 in the same place as your .map file. Inside it you make your own script object in the format the Beginner's Guide gives you, usually looking like '''void MyScript() { code goes here }'''. Then the game can "call" "threads" of that "script object" that will run until they end or are killed, so you can have more than one thread running of the same object concurrently. If you want multiple script objects, put them all in your <mapname>.script file and the game-engine will find them. You run scripts by the object name, not the file name.

'''Q. How do I run a script in-game?'''

'''A.''' A few common ways of calling a script object thread in-game are
# creating a target_callscriptfunction entity with the spawnarg: "call" "<name of your script object>", then creating some other entity (such as a button or trigger brush) that "targets" that entity;
# creating a button with the property "state_change_callback" "<script object>", which runs the script when pushed or triggered,
# Using [[Location_Settings#Script_calls]] to call a script when you enter or leave a location;
# triggering a script with the [[Objectives_Editor]] when you fulfill or fail an objective (possibly a hidden objective only for triggering the script);
# A script can call another thread in itself with the "thread" function; see the command in the link below.
# An entity can call a script when it spawns. Add a property/value either in the .def file or as a spawnarg on the entity: "ScriptEvent void <script object>(<parameters>);".
# The script "void main();" is always called at game start. So if you add code under that heading in your script file, it will run at game start.
There are other methods too. (Note, if you call a persistent script, i.e., it runs all game, be especially sure to avoid performance hits, or make it non-persistent if possible, that is, you "kill" it at some point in the game so it doesn't hog resources..)

'''Q. What are script events (aka commands or functions)?'''

'''A.''' A script event is a pre-made object that does something for you, usually to some game item you specify, just when you write it in your code (like '''$item.eventX();''' does X to item). Sometimes it wants parameters or arguments to run (the stuff in parentheses) and will give an error if you don't put the arguments in the parentheses in exactly the way it wants, with the right number of them & right data types, etc. And some of them return values too, especially the "get" functions, which are handed over to a variable (e.g., '''X = getValue();''', now X has the value. If X is an entity, you can even act on X as if it's the entity itself. Just be sure the data type of X and Value are the same, e.g. float, or string, or entity, etc, or you'll get an error).

'''Q. What are some common or useful script events for editing?'''

'''A.''' A list of all Doom3 and TDM script events are listed on this wiki page [[TDM_Script_Reference]], including the proper syntax (or this page, but it's down now: [http://www.modwiki.net/wiki/Script_events_%28Doom_3%29]), or also these two files in your Dark Mod folder (open with a text editor): scripts/doom_events.script, scripts/tdm_events.script. Note that TDM has some of its own script events, like setFrobable (in the tdm_events.script list).

A quick short list of common or useful script events good for editing is here: [[Script_Events_User-Friendly_List]], with syntax and description, and including TDM events. It doesn't list all script events and all details, just common & useful ones for actual mapping IMO. If you want the full list, use the TDM_Script_Reference link I gave above.

== World Building ==

'''Q. What's a good way to make caves?'''

'''A.''' Some tips are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__204909] & [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__289484] Instructions for quick-cavern pattern building is here [http://forums.thedarkmod.com/topic/14469-quick-caverns-recipe/page__view__findpost__p__304250]

'''Q. How do I make a good looking roof using clean brushwork, including with an attic inside?'''

'''A.''' Here are descriptions of method that all use a similar trick [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__325945], [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__325944], [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__244109]. The trick is to "cut out" a roof from a square brush using the clipper tool. Avoid rotating brushes to make it by hand. Alternatively, use patches over a rectangular under-structure of BSP brushes, although this is not good if you want a portaled attic.

'''Q. What's a good way for making a city area that performs well?'''

'''A.''' Sotha gave a good method in this post. [http://forums.thedarkmod.com/topic/10003-so-what-are-you-working-on-right-now/page__view__findpost__p__312133]

'''Q. What's a good way for making a forest or a big outdoorsy area?'''

'''A.''' One good method is making large "rooms" in the shape of a big oval cylinder with very high natural-looking "rocky" & skybox walls and uneven ground using patches, filling it with trees and hiding some of the walls behind trees and greenery (you could also fill it with thick cylinder brushes of different sizes with bark texture to look like more trees, and place branches coming off them or to make a canopy), and possibly filling it with tons of grass (using [[SEED]]) and rocks and streams, with visportaled openings at "kiss points" in the walls to other large oval rooms at different orientations (maybe 2-5 connections per oval) so there's a dense web of interconnected forested rooms that (sort of) appear to be one big dense forest to the player. Some useful things to use are the [[Object_detail]], [[SEED]], and [[LOD]] systems. See the blueprint for the Thief 2 level Trail of Blood for a rough idea: [http://thief.wikia.com/wiki/T2_M10_Trail_of_Blood?file=T2_m10a_editor_colored.gif]. For good examples in Dark Radiant, look at the construction of mission 3 of No Honor Among Thieves ("No Honor Among Anyone") and Shadowhide's slenderman forest map. (Somebody post links to screenshots of those maps in DR, or remind me to.)

'''Q. How do I make uneven ground?'''

'''A.''' One method is by burying patches into the ground that stick out and make the ground lumpy as described here [http://forums.thedarkmod.com/topic/13338-newbie-mapper-tip-making-uneven-ground/page__view__findpost__p__274917]. For more encompassing unevenness, you can use much larger patches laid over square caulk brushes underneath that seal the leaf to make the entire ground uneven.

'''Q. How do I make a natural looking road where there isn't a sharp seam between the road material and grass but a nice fading transition?'''

'''A.''' See the Wiki page for [[Roads]].

'''Q. How do I make curved ceilings and archways?'''

'''A.''' Use patches. Here's a list of some good tutorials for this sort of thing [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__254764]. Also look at this wiki page [[Patches#Archways]].

'''Q. What's a way to get good-looking fog in my mission?'''

'''A.''' There are numerous values to make good fog. The setup for the fog from Fidcal's Heart mission is here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__248277].

'''Q. What are some tips to making a better looking map?'''

'''A.''' See this wiki entry [[10_Simple_Tricks_for_Better_Looking_Maps]].

'''Q. What's a good method or plan-of-action for building?'''

'''A.''' This is a matter of personal preference, but a method that professionals use is called the "stepwise refinement" method. It means you build the *entire* space of your mission first in rough blocks (so you have it all planned out first), then refine the whole thing in increasingly more detailed steps section by section, leaving the most fine detailing towards the end. It can help to use DR's Layer system to organize your building by sections too, without other sections interfering. Also, when you're drawing your map, think about arranging space into winding "rooms" (so there's no long lines of sight), even outside with tunnels, walls and skybox; and think about visPortal placement right at the start. Also think about the gameplay-performance balance of shadowing-lights & AI when thinking about placing them.

'''Q. How do I cleanly connect two brush edges meeting together, especially at a diagonal?'''

'''A.''' See this post [[http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__257111]].

'''Q. What's a method for building very fast & efficiently?'''

'''A.''' Sotha came up with "modular" approach where you build a few stock modules of architecture that you can combine to make a lot of geometry very quickly and efficiently. Here's his description: [http://forums.thedarkmod.com/topic/12833-sir-taffsalots-mapping-thread/page__view__findpost__p__290747]

'''Q. How do I make a good looking waterfall?'''

'''A.''' There's a discussion about this in this thread [http://forums.thedarkmod.com/topic/11901-waterfalls/page__pid__303963#entry303963]. For a small waterfall, a white foamy particle effect raining down by itself looks good. You can copy Bikerdude's example from St. Alban's Cathedral. [http://www.youtube.com/watch?v=gIrZDpc1m68]. For a bigger waterfall, people talked about a combination of a flowing vertical water block with the foamy particle effect towards the bottom.

'''Q. How do I make a nice little pond.'''

'''A.''' See this wiki entry [[How_to_create_a_pond]]. This thread [http://forums.thedarkmod.com/topic/14647-how-can-i-make-a-realistic-looking-pond/page__view__findpost__p__308916] has discussion on it.

== Patches! ==

'''Q. Is it possible to split patches?'''

'''A.''' See this tutorial on it [[Patch_Splitting_-_Basic_Tutorial]].

'''Q. How do I bend patches?'''

'''A.''' See the instructions at [[Patches#Bending_Patches.2C_Curves.2C_L-shapes.2C_etc]] (Here's another small tutorial in a post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__277350].)

'''Q. I want to use a patch to round off a corner.'''

'''A.''' See this part of the Patch wiki page [[Patches#Round_and_Soft]].

'''Q. How can I make a perfect circle with patches?'''

'''A.''' Select verts of 4 corners, select the "rotate and scale" tool, and use the value "0.9428" to scale "up" (actually down) in the 2 corresponding axis of the scale tool. See this post [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__279356].

'''Q. How do I make a dome or sphere?'''

'''A.''' Make a cone patch and drag down the top vertex to form a dome. Invert the matrix if you want an internal dome or thicken if you want it to be visible inside and out. A sphere is just two of these stuck together. Also tweak the tesselation in patch inspector if it is too chunky. You can have fun with the textures though; try fit. If you totally flatten the dome you have a disc which can produce some nice texture effects, eg, the marble floor centrepiece or a round rug. Drag a side to make it oval. See this post for a picture [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__233107].

'''Q. How do you align a texture on a curved patch?'''

'''A.''' When you want to align properly texture to curved patch like this one in the image [NB: image is missing], divide a brush according to the angle of the patch then use it's shader for your purpose. ... I made it with one edge is at one end of the curved patch and the other edge is at the other end. It gets distortions without this way.

== Events and SFX ==

'''Q. How do I trigger an earthquake event?'''

'''A.''' Earthquakes can be done with a speaker. Just use the spawnarg "s_shakes" "1" on the speaker, and the screen will shake violently however loud the sound gets.

'''Q. How do I emulate something like a blizzard or dust storm?'''

'''A.''' Doom3 made a dust storm area, and the same method can be used to make a blizzard, so it's possible. I'm leaving this here to look up instructions for future reference.

'''Q. How do I make the screen fade to black (or some other color), or from black back to the game.'''

'''A.''' Trigger a script with the functions fadeIn [http://www.modwiki.net/wiki/FadeIn_%28script_event%29], fadeOut [http://www.modwiki.net/wiki/FadeOut_%28script_event%29], or FadeTo [http://www.modwiki.net/wiki/FadeTo_%28script_event%29].

== Textures ==

'''Q. What's a quick way to align textures between two surfaces?'''

'''A.''' For two brushes, select the first surface, then '''edit --> copy shader''', then click on the second surface and '''edit --> paste shader'''. This will seamlessly match the 2nd surface to the texture of the 1st. DR also comes with a useful tool for texture alignment, [[Texture_Tool]], which you bring up with Ctrl+Alt+T. If it's textures on two patches, you can follow these directions: [http://forums.thedarkmod.com/topic/14034-tutorial-for-road-creation/page__view__findpost__p__294114]

'''Q. How do I randomize the position of textures on multiple brushes, e.g., for a row of stairs or pillars all with the same texture that I want to look different?'''

'''A.''' Select multiple faces and in the surface inspector, press the natural button once you set the scale properly.

'''Q. Can I blend textures?'''

'''A.''' Yes. This is particularly good for dirtying some textures up by blending in a grime texture. You can blend textures with a custom material file. Link to instructions coming. Also see the entry for [[Basic_Material_File]].

'''Q. How about blending texture transitions so there isn't a sharp seam, e.g., for a dirt path in grass?'''

'''A1.''' DR comes with grass edge transition decal patches to overlay the hard edges. Read how to set it up here [[Grass_Edges]], or a more detailed tutorial on making roads here [[Roads]].

'''A2.''' In NHAT blended terrain was made from patches broken into segments then exported as ASE models. Then the models were vertex painted in Blender and imported back into Dark Radiant. See this tutorial [[DrVertexBlend_(tutorial)]].

'''Q. How do I set the color for some textures (like glowing mushrooms) and make lightbulbs go dark when turned off?

'''A.''' "Colorme" textures allow you to set the color with a spawnarg. So e.g. for colored mushrooms, choose a colorme skin with the spawnarg like "skin" "mushroom_selflit_green_colorme" and choose the color with a spawnarg like "_color" "0.24 0.50 0.40" (where the value is the RGB values you want). For lightbulbs you can trigger a colorme texture switch with the lightswitch (so it switches between "lit up" and "black"). Instructions on that coming.

'''Q. What's a fast way to put different textures on a lot of objects?'''

'''A.''' 1. Click the mouse wheel on the texture to copy it. 2. To paste it naturally (i.e., in a random position): shift+mousewheel click. 3. To just paste it: ctrl+mousewheel click.

'''Q. Can you tile a texture a specific number of times to fit a surface?'''

'''A.''' When you want to tile a texture a certain number of times, enter the values 1/X and 1/Y (you need to compute them in your head) in the little boxes in the surface inspector, then press "Fit". It will tile your texture horizontally X times and vertically Y times. You can also enter things like "2" and "1" and get a texture that only occupies half of the width. You can then use the "Right" or "Left" buttons to align it quickly at the ends. Pro-tip: Press CTRL+ALT+T to open the texture tool, it allows super quick aligning of textures on patches. Esp. useful for decals where the decal texture consists of multiple decals.

== Readables & GUIs ==

'''Q. How do I put custom art in a book or scroll, like a picture?'''

'''A.''' Use a custom .gui. Here's a rough idea to get you started [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__263836]. I'll try to put better instructions in later.

'''Q. How do I trigger a text message to pop up and say something?'''

'''A.''' Create an entity: darkmod > targets > atdm:gui_message and give it the properties/values that you want. Popups will explain each one. You can target it with a triggering entity or trigger it from a script or any other triggering mechanism. An example is here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__256592]

== Lighting and Sound ==

'''Q. How do I add music or ambient sounds?''' '''Q. Can I dynamically adjust the ambient lighting?'''

'''A.''' For both of these things, check out the article for [[Location Settings]]

{{editing|sort=Editing FAQ (Troubleshooting & How-To)}} {{tutorial-editing|sort=Editing FAQ (Troubleshooting & How-To)}} {{darkradiant|sort=Editing FAQ (Troubleshooting & How-To)}}

'''Q. How do I set up Reverb (EAX) settings for my rooms? (E.g., the echo of a large hall, etc.)'''

'''A.''' Create a text file and name it <mapname>.eax; place it in your .pk4 with your .map file; and in it create entries by location name with the values you want for that location. See this wiki entry to see the format & values [[Setting_Reverb_Data_of_Rooms_(EAX)]].

Editing FAQ - Troubleshooting & How-To

2013-11-09T01:13:32Z

Demagogue: /* Performance Issues */

Below are some common issues and questions mappers have had in the Editor's Guild forum with common solutions. Some of this assumes you've already gone through the [[A_-_Z_Beginner_Full_Guide_Start_Here!]], [[Startpack_Mappers'_Guide]], and [[Dark_Radiant_Must_Know_Basic_Intro]]. (If you know a FAQ not here and worth going in this list, and you know the right answer(!), or you can improve an existing answer, please add it if you have edit control or PM it to a team-member if you don't.)

= Troubleshooting FAQ =

== Rendering & VisPortal Issues ==

'''Q. Some of my brushes have disappeared or turned black and won't render.'''

'''A.''' This can happen when two touching brushes around the seam are not perfectly flush with one another and the rendering hiccups for those brushes & brushes behind it, either there's a tiny wedge or overlap or gap or weird angle between them. The usual solution is to make sure the brushes are snapped to the grid and perfectly flush against one another, or more generally to simplify the brushwork around the seam of the disappearing brushes.

'''Q. My visportal is not showing up or not closing like it should (you can check this with by typing "r_showportals 1" in the console. The portal edge will show green when open and red when closed.).'''

'''A.''' A common reason for that is that the two areas separated by the portal are not hermetically sealed and there's an internal leak, either (1) there may be an unportaled gap between the two, possibly covered up by func_static (which do not seal) or possibly caused by an inadvertent hole created by the first FAQ question above, or (2) an internal leak can happen when all sides of the visportal are not buried in or flush against sealing brushes, and there's a gap between the visportal and brush, or possibly even a tiny gap just touching the visportal side is enough to break it. A way to check if there's an internal leak, and locating it if there is, is described here: [[Visportals#Trouble-shooting]]. Other reasons it might fail are also described there (such as accidentally changing a nodraw texture to something else).

'''Q. I can see other rooms behind a mirror (or any reflective surface) through it, instead of just a reflection.'''

'''A.''' The area behind a mirror should be in a separate leaf (visportaled area) behind a closed visportal so it doesn't render. This problem usually means the two areas aren't in separate leafs, the portal isn't closed, or there's an internal leak between the areas in front of and behind the mirror.

'''Q. Help! I'm having rendering & visPortal issues all over the place ... broken portals, sparkly lines, disappearing brushes, z-fighting, uneven walls, etc.'''

'''A.''' As a general piece of advice, messy brushwork leads to trouble one way or another. To keep your brushwork clean:
* keep snapped to the grid (Ctrl+G toggles) & stay away from small grid levels (Typing a number or Plus/Minus changes the grid scale; 8 is a good starting grid; staying at or above 2 or 4 is fine for most stuff; going below 1 is usually just for special situations).
* Make brush intersections perfectly flush.
* Stay away from unnecessary tiny brushes & wedges (leave detail work to func_statics; brushes are for closing off leafs and the void. Of course you can do fine detail work with brushes & convert them to a func_static).
* Don't use the "CGS Subtract" tool if it will shatter the brush into tiny slivers; use the cut tool instead (open by pushing "X").
* You can use patches for uneven geometry with square brushes underneath textured with caulk.
* When rotating geometry, avoid weird angles when you can (where vertexes end up off the grid), and for multi-brush structures, build the whole thing first *then* rotate it all together instead of rotating & placing each brush individually.
These aren't rules set in concrete if you want to do something special once in a while, but general rules of thumb that will make life a lot easier if you generally stick to them.

== Crashes and Warnings ==

'''Q. My map has a leak in it, but a pointfile either isn't generated or doesn't make sense. (A pointfile is generated when dmap occurs and there's a leak, then you open DarkRadient and click File>Pointfile to see it. It normally runs a red line that ends in the void, pointing out the leak).'''

'''A.''' Make sure a gap isn't covered up with func_statics. If the origin of a model is in the void it will also cause a leak with a non-sense pointfile. Read more on the [[Leaking maps]] page.

'''Q. How do I scroll up through the console output to see what a problem was during dmap or map or in-game?'''

'''A.''' Use the mouse wheel or PageUp/Down to scroll through the console.

'''Q. I'm getting an error message "warning: aas is out of date" once my map has loaded. What does it mean and what do I do?'''

'''A.''' The AAS is for AI pathfinding. It usually means you changed brushwork and started a map without dmapping first. The solution is to dmap. If you dmap and still get the warning, delete your .aasxx, .proc, and .cm files in the maps folder and dmap again. If you're still getting a warning, then it could be a sign that something in your map is breaking the AAS pathfinding. Try monsterclipping tricky areas for the AI to path (like around objects and uneven ground) or clean up messy brushwork that might break the dmapping like sliver brushes.

'''Q. I have encountered a malloc failure error while dmapping my level. Instead of finishing with the dmap operation, it crashes midway with an error message.'''

'''A1.''' One solution to this is given in the Dmap wiki entry here: [[Dmap#Malloc_Errors]].

'''A2.''' This is what I've done to fix this exact issue. Open the map in DarkRadiant, select everything, copy to clipboard. Open another instance of DarkRadiant and paste from clipboard. Save as new filename and dmap new file and that has worked 3 times now with random unresolvable crashes.

'''A3.''' GC and I have found correlations between visportalling and mAlloc errors. Time to re-arrange your visportals. In NHAT, we had many malloc problems until we retooled how each area was portaled. Originally, every other visleaf had tons of entities, while half had hardly any. That's not neccessarily bad, but it strains the dmapper when one or two visleafs are cluttered with entities that really bloat your mapname.proc file. We added a few more portals to even out entity distribution, and dmap was happy again.

== Performance Issues ==

'''Q. My map is so slow. How do I improve performance?'''

'''A.''' See these wiki entry: [[Performance:_Essential_Must-Knows]]. Tips include:
* Reduce AI [[Pathfinding]] with Monsterclipping helps performance, simplifying complex bumpy surfaces into 1 smooth monsterclipped surface (or raise the monsterclip to inside the ceiling and there is no pathfinding computation at all), or excluding entire surfaces AI should never walk on, like detail brushwork or some roofs.
* Use [[Interleaved_Thinking_optimization]]. Reducing AI think-time helps performance quite a bit.
* break-up long lines of sight,
* improve visportal & leaf placement (so less architecture is rendered at a time),
* use fewer AI,
* convert ornamental brushwork into func_static,
* reduce the overlap of light sources on surfaces by adjusting their placement & reducing their light-radius. (Every time a new light hits a surface, it's another render pass. So 4 lights hitting a surface processes it 4 times. If only 1 light hit it, its lighting is processed in 1/4 the time), and
* set objects and lights to "noshadow" if it won't be noticable to the player or affect gameplay (possibly in combination with low-poly shadow meshes or shadowy decals. Note that "noshadow" has two jobs. Put on lights, it means that light will cast no shadows on any object. Put on objects, it means that object will not cast a shadow from any light.)

There are also lots of other tricks out there if you check around the forums, including more advanced & optional tricks such as using the [[LOD]] system or [[SEED]] system, or even crazier tricks (cross-leaf func_statics, skybox architecture, Strombine lighting, Camera Cubemapped Visportal Patches, lots of crazy tricks out there), that you don't have to worry about if you're a new mapper but you can ask us about or search for in the forum if you're curious. Generally speaking there are pros and cons trade-offs between performance & dazzle for many things (like lights or visportal placement); so it's good to think about the best performance-dazzle balance for your scene. E.g, lots of highpoly brushwork, lights, & AI can look good in a small or medium room, but may not be worth the performance hit in a big courtyard, and try to find ways to get better performance "for free" without the player noticing anything missing, like smart use of noshadows, monsterclips, and interleaved thinking distances.

== Gameplay Issues that Mappers sometimes Overlook ==

'''Below is a list of common gameplay issues that players sometimes complain about and that mappers & testers sometimes overlook or should at least be aware of.'''

- Players find it very difficult to frob objects (loot, keys, readables) when the frob distance is set too short or the space is awkward (like in a drawer or up on a wall, etc). In testing, please double-check that every frobable object is easy to frob from a comfortable place, and increase the frob distance if it's not, erring on the side of more space. (See the question on making frobbing easier under "Handling Objects" below for more information.)

- Objects can get stuck into brushwork while moving them around.

- Players can get stuck in narrow spaces and can't mantle out, so try to avoid this kind of geometry if possible.

- A very low ceiling can prevent hitting AI with a BJ, so try to avoid it when AI are around.

- Make sure AI have a flee path.

- Some players would like the ability to drop used keys and other inventory items, done by turning the can_be_dropped property to true, unless for gameplay reasons you don't want to.

- Some players don't like long readables that don't get to the point. At least be conscious of how your readables read to a player.

- Think about how you want to handle non-functioning doors (or other "unnatural" situations like windows that can open) in a way that visually or fairly communicates to the player that something is special about this door or window, but isn't too immersion breaking either.

== Issues with Objects ==

'''Q. My streetlight, candle, lamp, light-creating object, causes a weird shadow I want to get rid of.'''

'''A.''' Put the spawnarg "noshadows" "1" on the offending object.

== AI Issues ==

'''Q. My AI will not pass through a visportal no matter how I set up the path nodes.'''

'''A.''' Check that the sides of the visportal use the nodraw texture (except for the portal-face itself of course).

'''Q. How do you get AI to walk on complex terrain patches or func_statics?'''

'''A.''' You can always lay down invisible monsterclip brushes and the AI can walk on it. Overlay with a brush with a "material" clip texture so it causes the right sound for footsteps.'''

== Problems with Patches ==

'''Q. I have 2 curved patches and they're not aligning. What do I do?'''

'''A.''' See this wiki page [[Patch_Troubleshooter]].

'''Q. My patch is rendering strangely, like fractured into slivers.'''

'''A.''' See this wiki page [[Patch_Troubleshooter]].

== Issues with Lighting & Sound ==

'''Q. Some of the parallel lights I use for moonlight aren't giving off any light.'''

'''A.''' This is a known problem with parallel lights. For some reason in some arrangements you get no light at all. Just fiddle with it a bit - move it slightly, change the radii, move the vertex a bit - and it should suddenly work. Once you've got it working then it's stable. Likely the code chokes on certain values in its calculations. ... Also, to help optimize your moonlight, you should adjust the radius so it's only as big as it needs to be. You may also want to move the actual position of the little moon cube in the skybox to match the parallel light (and make sure to fix the texture on it if you mess it up - hint: lock textures before moving cube to make it easy)

= General How-To Editing FAQ =

== Dark Radient Questions ==

'''Q. How do I see all the default properties already on an object?'''

'''A.''' In the entity inspector there's a checkbox near the top that says "Show Inherited Properties". Click that box.

'''Q. What are some basic units, scales, limits, maxs, and mins of various things when editing?'''

'''A.''' A list of all these things is here: [[Limits,_Max,_Min,_Stats,_etc]].

'''Q. Can I manipulate brushes to resize and reshape them?'''

'''A.''' Yes. In DarkRadient you can select a brush and push "V" to select verticies to drag and resize, "E" to select edge(s) to drag and resize, and "F" to select face(s) to drag and resize. "Ctrl+#" makes a selected brush be #-sided. You can also use the Brush>Prism and Brush>Cone to convert a brush to those shapes.

'''Q. What are some common DR shortcut commands?'''

'''A.'''
* "H" hides selected items.
* "I" inverts selected.
* "Ctrl+I" inverts a patch's normal.
* "J" brings up entity list.
* "Ctrl+K" makes 1st-selected-entity "target" 2nd-selected-entity.
* "L" brings up light inspector.
* "Ctrl+L" brings up the Layers menu.
* "N" brings up entity inspector.
* "T" brings up texture browser.
* "X" go into clipper mode.
* Brush manipulation modes: are "R" rotate brush, "Q" free-move & resize, "W" translate-move.

'''Q. How do I make my own shortcut key commands?'''

'''A.''' Under the Edit menu, at the bottom is "Keyboard Shortcuts" which allows you to set your own shortcuts.

'''Q. I screwed something up! What do I do?!'''

'''A.''' Ctrl+Z undos. Ctrl+Y redos.

'''Q. Is there a way to organize & simplify building, so I can build one section at a time without other sections getting in the way?'''

'''A.''' DR has a [[Layers]] function that lets you build one "layer" at a time (open with ctrl+L or View>Layers). It also improves DR performance, which is handy as the map gets bigger.

'''Q. How do I set up things like the pre-game shop, the player inventory, and an in-game map?'''

'''A.''' All these things are described in the Startpack Mappers' Guide: [[Startpack_Mappers'_Guide#Ammo.2C_Weapons.2C_Player_Tools.2C_Start_Inventory]], [[Startpack_Mappers'_Guide#Purchase_Shop]], [[Startpack_Mappers'_Guide#Adding_an_In-game_Map_to_your_FM]]

'''Q. How do I put spawnargs on def_attached entities?'''

'''A.''' You can put spawnargs on def_attached entities by using the spawnarg "set SPAWNARGNAME on ATTACHMENTNAME" "value" on the base entity. Here's an example of setting a color property on a flame attachment to a torch "set _color on flame" "0.2 0.2 0.9". Read more here [[Combined_light_entities#Setting_spawnargs]].

'''Q. What's an easy way to find materials in DR?'''

'''A.''' Tip to help find materials in Dark Radiant's materials browser:
# Point to Textures (or any tree).
# Shift + Right key to fully open the tree.
# Type the key letters of what you want to find.
# Up/down arrows to go to next/previous occurrence.
# Esc to get out of input field.
Oh yeah, avoid F3 because that is likely to switch to render mode which in my case crashes DR (but may not if the map is small).

'''Q. How do I make an N-sided brush?'''

'''A.''' A quick way to make an N-sided brush is to highlight the brush and push cntl+N (N being the number of sides for the top face). So if you want a 5-sided brush, highlight it and push cntl+5. But the best way to get the walls of a multi-sided brush to line up seamlessly is still to use the clipper-tool and precisely cut off a slice. (And don't use CSG Subtract unless you know what you're doing and aren't creating a million splinters!)

== Console Questions ==

'''Q. How do I open the console?'''

'''A.''' Open the console with ctrl+alt+~ in a normal game, and just ~ when playing through "map".

'''Q. How do I scroll through the console output?'''

'''A.''' Use the mouse wheel or PageUp/PageDown.

'''Q.What's a list of all the Doom3 Console Commands and CVars?'''

'''A.''' A list of all commands & Cvars is here [http://www.doomwadstation.com/doom3/console/]. Darkmod Cvars are listed here [[Cvars_in_The_Dark_Mod]].

'''Q. What are some *useful* console commands and cvars for editing?'''

'''A.''' Here's one list: [[Console_Useful_Controls]]. Here's a list more tailored to mapping:

Commands:
"'''dmap <name>'''" compiles a map,
"'''give <name>'''" gives the player an item,
"'''god'''" player cannot be harmed,
"'''killmonsters'''" takes out all AI
"'''map <name>'''" loads a map to play,
"'''noclip'''" lets the player go through objects and walls,
"'''notarget'''" let's the player be invisible to AI,
"'''reloadDecls'''" will reload material defs without having to re-start TDM,
"'''reloadimages'''" does the same for lights and
"'''reloadSurface'''" for surfaces,
"'''saveRagdolls'''" saves the positions of all ragdolls to the .map file (see the FAQ under Handling AI),
"'''teleport <name>'''" teleports the player to an entity.
"'''tdm_show_loot'''" Shows loot.
"'''spawn <name>'''" spawns an entity:
spawn atdm:weapon_blackjack
spawn atdm:weapon_shortsword
spawn atdm:ammo_broadhead
spawn atdm:ammo_firearrow
spawn atdm:ammo_gasarrow
spawn atdm:ammo_mossarrow
spawn atdm:ammo_noisemaker
spawn atdm:ammo_ropearrow
spawn atdm:ammo_waterarrow
Append "inv_ammo_amount 50" to any of the above to spawn 50 arrows at once: spawn atdm:ammo_broadhead inv_ammo_amount 50
Cvars (1 turns on, 0 turns off, unless otherwise noted):
"'''com_showFPS 1'''",
"'''r_showLightCount 1'''" (colors shows the number of lights hitting a surface, black = 0, red = 1, blue = 2... etc),
"'''r_showPortals 1'''" (red=closed,green=open) If your portals dont show up they are most likely not sealing.
"'''r_showTris n'''" (n=1) Shows tris rendered directly, (n=2) shows overdrawn tri's, (n=3) shows all tri's, direct and indirect.

== Objectives ==

'''Q. How do I set up a put-object-here objective?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__182924]

'''Q. How do I set up a "ghosting" objective (e.g., you are busted if you are seen.)'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__204695]

== Handling Objects ==

'''Q. How do I attach a door handle to a door?'''

'''A.''' Just position the handle and input "bind" and the door entity ID/name as a spawnarg.

'''Q. How do I make an object into loot?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__182921]

'''Q. How do I make an entity frobable?'''

'''A.''' See the entry for [[Making an Entity frobable]].

'''Q. Ok it's frobable, but doesn't fall or move. How do I make an entity act like a world object?'''

'''A.''' You need to make the object a moveable, see [[Moveables]].

'''Q. How do I get a lever or button to open a door?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__212036]

'''Q. How do I put some text on a sign or wall?'''

'''A.''' You can use this method [http://forums.thedarkmod.com/topic/11159-add-text-to-your-signs-signposts-walls-etc/]

'''Q. How do I bind something to a rope (like a body) so it doesn't fall?'''

'''A.''' Dynamic ropes are unreliable, so it's good to use a func_static like a chain or make a func_static rope from a cylinder brush. For a ragdoll, place the ragdoll so he clips into the func_static. You need to bind the ragdoll to the chain (so the spawnarg is on the ragdoll), with "bind" "func_static_...", where func_static_... is the chain. Or, through DR, you can just select the entity you want to attach (the ragdoll), then also select the thing you want to attach it to (the chain), and in the menus select "Entity" - "Bind selected entities". But it's been reported the clipping does the job, not binding. See this link [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__221262]

'''Q. How do I make something switch from frobable to unfrobable like a used lever, or unfrobable to frobable like contents in a chest or drawer you don't want frobable until it's open?'''

'''A.''' Make a brush around the object with a clip texture and convert it to an atdm:target_set_frobable entity, with the property "start_frobable" 1 or 0 (which mean true or false) depending on your case (it affects everything inside), and a triggering entity, such as the lever or the chest itself, that targets the set_frobable entity that triggers the switch when it's frobbed. For the record, you can also switch the frobability of an object in a script with the command: '''$<entityname>.setFrobable(n);''', where n is "1" to make it frobable and "0" for unfrobable.

'''Q. How do I make breakable glass?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__222734]. You basically convert your glass brush to a func_fracture entity and set the "health" spawnarg to the value you want the glass to break at.

'''Q. What about an object that gets increasingly damaged-looking as you hit it?'''

'''A.''' Use a func_damagable entity, which replaces its model and/or shader with increasingly "damaged" versions (as many stages as you like) when its health goes below the threshold you set with the "health" spawnarg, and you can use "target" to trigger something when damage occurs (such as a sound effect or event). See here for details on the spawnargs involved in setting it up: [http://www.modwiki.net/wiki/Func_damagable_(entity)]

'''Q. How do I make an object that you can frob and it does something or something happens?'''

'''A.''' If it's an object you made from patches or brushes, make it into a frobable func_static, or if it's already a func_static, make sure it's frobable ([[Making an Entity frobable]]). Then give it a Frob response whose effect is a trigger, and give it a "target" spawnarg to the entity that causes your effect when triggered.

'''Q. Can a lever or button target multiple entities?'''

'''A.''' Yes! Use the spawnargs "target1", "target2", "target3", etc, with each entity-target as a value. A quicker way is to use the keyboard shortcut Ctrl+K. Select the button or lever, then select the target-entity and hit Ctrl+K. De-select the target-entity then select the next one, hit Ctrl+K again. Each time adds a new target to the switch. (Many other spawnargs allow you to have multiple entries by numbering them, such as bind and def_attach.)

'''Q. How do I make a rotating entity, like a fan?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__242385]

'''Q. How do I make objects non-solid so they still render but the player can walk through them?'''

'''A.''' Add the spawnarg: noclipmodel 1 to turn them into non-solids.

'''Q. How do I make a firefly or will-o-wisp, basically a glowing ball that floats around?'''

'''A.''' This is a rough explanation to help you get started. A firefly is a func_emitter. Click the model property then use the button bottom right to select a suitable particle effect, possibly tdm_glare_lamp_01.prt. Bind to something invisible that will move it along a path, typically a func_mover with nurb curves used as the path. A tutorial for setting up nurb curves is here [http://www.doom3world.org/phpbb2/viewtopic.php?t=5123].

'''Q. How do I trigger an event from something in the player's inventory?'''

'''A.''' give the object a "target" to trigger and also the property/value: scriptobject InvTriggerScript. If your object does not already go in the inventory then use the entity: items > custom > atdm:moveable_custom_item. If you get a collision model error then ask on the forums for help (or read the wiki entry for [[Moveables]]).

'''Q. How do I teleport an entity?'''

'''A.''' Use targets/atdm:teleport. See this wiki page [[Teleporting_entities]].

'''Q. How do I make a custom inventory item with its own inventory icon graphic?'''

'''A.''' See this entry [[A_-_Z_Beginner_Full_Guide_Page_6#Special_Items]] for setting the inventory category, loot type, inventory name and inventory icon. To repeat the instructions for a custom icon: on the object put the property "inv_icon" with a value "guis/assets/hud/inventory_icons/<name>.tga" (substitute whatever name you gave it for <name>), and package your .pk4 to put your image file in that relative location. You can also see other inventory_icons there and can use an existing one, or package your .pk4 to replace an existing one with your custom one. A method for making an inventory icon is described here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__259172] (be sure to use an alpha channel to make the background transparent, tutorial: [http://www.axialis.com/tutorials/tutorial-misc001.html]).

'''Q. How do make an object that's hard to frob easier to frob?'''

'''A.''' One easy way is to add this property: frobbox_size 5. If it's still hard, see this post for other things you can do. [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__228245]

'''Q. How do I make a candle you can pinch to go out?'''

'''A.''' I made a bunch of pinchable non-moveable candles into my WIP like this:
# Make a func_static candlestick. place light source entity candleflame on it.
# Give the candlestick "frobable 1."
# Give the candlestick S&R response frob, extinguish light and candleflame name.
# You can optionally add another response frob to trigger a speaker with a "snuff" sound effect.
# Done.
You can copy the entity bunch around and all the params should update correctly for the new replica. Frobbing will not relight it: the player needs to relit them with a flame source.

== Handling AI ==

'''Q. How do I make sure a guard can unlock a door?'''

'''A.''' There are a few different ways, explained here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__217915]

'''Q. How do I attach a key or purse to an AI's belt, or similar kinds of attachments?'''

'''A.''' The easiest way is with "bind". Place the key or purse around the belt area where you want it, sticking a little farther out than usual, and rotate it as desired. On the key add the property "bind" with the value of the AI's entity-ID or name, then the property "bindToJoint" with the value "leftHips_dummy" or "rightHips_dummy" as needed. For attaching things in other places (like a ring or hat or necklace), it's the same general principle but you should look up the joint to attach to. A list of all the joint names is here: [[BindToJoint]]. See this wiki entry for more info [[Attaching_Items]]. For another method using def_attach see [[Attaching_Props_to_AI]], and this post for an example of the spawnargs involved [http://forums.thedarkmod.com/topic/13084-ai-attach-keys/page__view__findpost__p__276064]. The issue with def_attach is that the attached thing spawns at its own rotation angle, which might not look great and is tricky to change (if you insist, see [[AI_Attachment_Ingame_Editing]] and [[Cvars_in_The_Dark_Mod#Attachment_related]]). With bind you just place and "bind", and it stays where you put it.

'''Q. What about other kinds of attachments where special animations are involved, like torches and weapons?'''

'''A.''' For these you want to use Def_Attach. See this wiki entry [[Attaching_Props_to_AI]]. For heads & weapons specifically see this wiki entry [[Adding_Heads_and_Weapons_to_AI]]. (You can set spawnargs on the def_attached entities with the method described here [[Combined_light_entities#Setting_spawnargs]].)

'''Q. How do I mute an AI?'''

'''A.''' Give the AI the spawnarg: def_vocal_set atdm:ai_vocal_set_mute. If you only want to mute some barks, you'll have to modify the AI's .def file by hand, taking or commenting out the barks you don't want, and packaging the new def file in your mission's pk4. For coughing and animation based barks, see this post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__224558]

'''Q. Can I hide an AI until I trigger him?'''

'''A.''' No, the spawnarg "hide" doesn't work well with AI (they're made invisible, but still audibly there). Put the AI in a blueroom and use a teleport instead, or a teleporting script command. See the wiki entry for [[Teleporting_entities]]. Note, after teleporting an AI, pathing becomes a problem for it. See this post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__280818] and the previous posts on this issue to make sure the AI can path properly after a teleport.

'''Q. How do I manage AI teams, who is a friend, enemy and neutral?'''

'''A.''' To set the teams, see [[Relations]]. If you want to trigger a change in team with a script, see [[AI_Relations_(Scripting)]]. Another method to switch AI teams using S&R (stim & response) is described here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__256126] and see the entry [[Stim/Response]].

'''Q. How do I make an AI play an animation when I want?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__253169]. There may be other ways possible.

'''Q. How do I set or change the health of AI?'''

'''A.''' AI use the spawnarg "health" to set their hit points. To change it in-game, use a script and the function "setHealth".

'''Q. How do I pose ragdolls so they look naturally placed?'''

'''A.''' Save a backup, pose all the ragdolls in-game, then use the console command saveRagdolls which saves their positions to the .map file. cf. [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__265650].

'''Q. How do I make a scene of AI playing cards?'''

'''A.''' Probably the easiest thing to do is load the prefab (under AI), place it, and adjust it how you want.

'''Q. How do I make an AI frob something?'''

'''A.''' To get an AI to frob something, eg, a lever (doesn't work to pick up and carry) create a path_interact entity. You can include it in a normal pathing patrol. Give it these 2 spawnargs: ent <name of entity you want the AI to frob>; target <next path entity (if any)>. Note that the AI won't walk to this entity; you have to use a path_corner to get him where you want then target to the path_interact to get him to frob.

'''Q. How do I make an AI catch fire?'''

'''A.''' You can bind some unlit fires to an NPC (like a zombie) and shoot it when a fire arrow, he'll erupt in flames, but the flames won't damage him. You could also light him with a candle. I'd bet theres some way to make that actually kill the creature, or at least cause it damage. ... One improvement suggestion: When the the light gets the fire stim, target a trigger multiple, which delays for a 120-240 seconds and then turns the fire off. You could make the fire damaging by starting a trigger timer which applies the stim damage to the target every few seconds. Remember to switch off the timer when the flames are doused.

'''Q. How do I keep an AI ragdoll from sinking into the bed model, e.g., if he's KO'd?'''

'''A.''' I found one way to keep [an unconscious/dead ragdoll body] from sinking into the model below it is to use a platform of nodraw_solid underneath the body. You should be able to place such a brush within the bed model and test it with a ragdoll on the bed. Adjust it's top surface height until the body lays just on top of the bed (then delete the ragdoll)... then a blackjacked AI should be able to stay on top of the bed like the ragdoll did.

== The Player ==

'''Q. How do I do things with the player's inventory, like trigger an inventory item to be deleted, or an item to be added to the inventory, or one item being replaced with another item?'''

'''A.''' You can do all these things with a script (read [[A_Beginner's_Guide_to_Scripting]] and the scripting FAQ below to learn about scripting). Have your triggering mechanism trigger a target_callscriptfunction entity which calls a custom script, then use the appropriate script command in the script on $player1. A list of the commands is here [[Inventory#Scriptsupport]].
Useful commands are (replacing the "Item" variables with the item ID):
* '''$player1.addInvItem(inv_item);''' and
* '''$player1.replaceInvItem(oldItem, newItem);''' (note: If <newItem> is the $null_entity, <oldItem> is just removed and no replacement happens.)
For example, to remove a key from the player's inventory, use a command like: '''$player1.replaceInvItem ($key, $null_entity);'''

'''Q. How do I teleport the player?'''

'''A.''' Use base > info_player_teleport. Give it the spawnarg and value: target info_player_start_1. Give it the spawnarg: angle with a value if you want to force the player to turn to face a particular direction.

'''Q. How can I simulate a crawl for the player to pass under things like tables that he couldn't normally do?'''

'''A.''' See this post [[http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__229174]]

== Scripting ==

'''Q. How do I make a custom script?'''

'''A.''' First read [[A_Beginner's_Guide_to_Scripting]], [[Scripting_basics]], and [[My_first_map_script]] to learn the basics of scripting. You write a custom script as a text file named <mapname>.script and packaged in your .pk4 in the same place as your .map file. Inside it you make your own script object in the format the Beginner's Guide gives you, usually looking like '''void MyScript() { code goes here }'''. Then the game can "call" "threads" of that "script object" that will run until they end or are killed, so you can have more than one thread running of the same object concurrently. If you want multiple script objects, put them all in your <mapname>.script file and the game-engine will find them. You run scripts by the object name, not the file name.

'''Q. How do I run a script in-game?'''

'''A.''' A few common ways of calling a script object thread in-game are
# creating a target_callscriptfunction entity with the spawnarg: "call" "<name of your script object>", then creating some other entity (such as a button or trigger brush) that "targets" that entity;
# creating a button with the property "state_change_callback" "<script object>", which runs the script when pushed or triggered,
# Using [[Location_Settings#Script_calls]] to call a script when you enter or leave a location;
# triggering a script with the [[Objectives_Editor]] when you fulfill or fail an objective (possibly a hidden objective only for triggering the script);
# A script can call another thread in itself with the "thread" function; see the command in the link below.
# An entity can call a script when it spawns. Add a property/value either in the .def file or as a spawnarg on the entity: "ScriptEvent void <script object>(<parameters>);".
# The script "void main();" is always called at game start. So if you add code under that heading in your script file, it will run at game start.
There are other methods too. (Note, if you call a persistent script, i.e., it runs all game, be especially sure to avoid performance hits, or make it non-persistent if possible, that is, you "kill" it at some point in the game so it doesn't hog resources..)

'''Q. What are script events (aka commands or functions)?'''

'''A.''' A script event is a pre-made object that does something for you, usually to some game item you specify, just when you write it in your code (like '''$item.eventX();''' does X to item). Sometimes it wants parameters or arguments to run (the stuff in parentheses) and will give an error if you don't put the arguments in the parentheses in exactly the way it wants, with the right number of them & right data types, etc. And some of them return values too, especially the "get" functions, which are handed over to a variable (e.g., '''X = getValue();''', now X has the value. If X is an entity, you can even act on X as if it's the entity itself. Just be sure the data type of X and Value are the same, e.g. float, or string, or entity, etc, or you'll get an error).

'''Q. What are some common or useful script events for editing?'''

'''A.''' A list of all Doom3 and TDM script events are listed on this wiki page [[TDM_Script_Reference]], including the proper syntax (or this page, but it's down now: [http://www.modwiki.net/wiki/Script_events_%28Doom_3%29]), or also these two files in your Dark Mod folder (open with a text editor): scripts/doom_events.script, scripts/tdm_events.script. Note that TDM has some of its own script events, like setFrobable (in the tdm_events.script list).

A quick short list of common or useful script events good for editing is here: [[Script_Events_User-Friendly_List]], with syntax and description, and including TDM events. It doesn't list all script events and all details, just common & useful ones for actual mapping IMO. If you want the full list, use the TDM_Script_Reference link I gave above.

== World Building ==

'''Q. What's a good way to make caves?'''

'''A.''' Some tips are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__204909] & [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__289484] Instructions for quick-cavern pattern building is here [http://forums.thedarkmod.com/topic/14469-quick-caverns-recipe/page__view__findpost__p__304250]

'''Q. How do I make a good looking roof using clean brushwork, including with an attic inside?'''

'''A.''' Here are descriptions of method that all use a similar trick [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__325945], [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__325944], [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__244109]. The trick is to "cut out" a roof from a square brush using the clipper tool. Avoid rotating brushes to make it by hand. Alternatively, use patches over a rectangular under-structure of BSP brushes, although this is not good if you want a portaled attic.

'''Q. What's a good way for making a city area that performs well?'''

'''A.''' Sotha gave a good method in this post. [http://forums.thedarkmod.com/topic/10003-so-what-are-you-working-on-right-now/page__view__findpost__p__312133]

'''Q. What's a good way for making a forest or a big outdoorsy area?'''

'''A.''' One good method is making large "rooms" in the shape of a big oval cylinder with very high natural-looking "rocky" & skybox walls and uneven ground using patches, filling it with trees and hiding some of the walls behind trees and greenery (you could also fill it with thick cylinder brushes of different sizes with bark texture to look like more trees, and place branches coming off them or to make a canopy), and possibly filling it with tons of grass (using [[SEED]]) and rocks and streams, with visportaled openings at "kiss points" in the walls to other large oval rooms at different orientations (maybe 2-5 connections per oval) so there's a dense web of interconnected forested rooms that (sort of) appear to be one big dense forest to the player. Some useful things to use are the [[Object_detail]], [[SEED]], and [[LOD]] systems. See the blueprint for the Thief 2 level Trail of Blood for a rough idea: [http://thief.wikia.com/wiki/T2_M10_Trail_of_Blood?file=T2_m10a_editor_colored.gif]. For good examples in Dark Radiant, look at the construction of mission 3 of No Honor Among Thieves ("No Honor Among Anyone") and Shadowhide's slenderman forest map. (Somebody post links to screenshots of those maps in DR, or remind me to.)

'''Q. How do I make uneven ground?'''

'''A.''' One method is by burying patches into the ground that stick out and make the ground lumpy as described here [http://forums.thedarkmod.com/topic/13338-newbie-mapper-tip-making-uneven-ground/page__view__findpost__p__274917]. For more encompassing unevenness, you can use much larger patches laid over square caulk brushes underneath that seal the leaf to make the entire ground uneven.

'''Q. How do I make a natural looking road where there isn't a sharp seam between the road material and grass but a nice fading transition?'''

'''A.''' See the Wiki page for [[Roads]].

'''Q. How do I make curved ceilings and archways?'''

'''A.''' Use patches. Here's a list of some good tutorials for this sort of thing [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__254764]. Also look at this wiki page [[Patches#Archways]].

'''Q. What's a way to get good-looking fog in my mission?'''

'''A.''' There are numerous values to make good fog. The setup for the fog from Fidcal's Heart mission is here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__248277].

'''Q. What are some tips to making a better looking map?'''

'''A.''' See this wiki entry [[10_Simple_Tricks_for_Better_Looking_Maps]].

'''Q. What's a good method or plan-of-action for building?'''

'''A.''' This is a matter of personal preference, but a method that professionals use is called the "stepwise refinement" method. It means you build the *entire* space of your mission first in rough blocks (so you have it all planned out first), then refine the whole thing in increasingly more detailed steps section by section, leaving the most fine detailing towards the end. It can help to use DR's Layer system to organize your building by sections too, without other sections interfering. Also, when you're drawing your map, think about arranging space into winding "rooms" (so there's no long lines of sight), even outside with tunnels, walls and skybox; and think about visPortal placement right at the start. Also think about the gameplay-performance balance of shadowing-lights & AI when thinking about placing them.

'''Q. How do I cleanly connect two brush edges meeting together, especially at a diagonal?'''

'''A.''' See this post [[http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__257111]].

'''Q. What's a method for building very fast & efficiently?'''

'''A.''' Sotha came up with "modular" approach where you build a few stock modules of architecture that you can combine to make a lot of geometry very quickly and efficiently. Here's his description: [http://forums.thedarkmod.com/topic/12833-sir-taffsalots-mapping-thread/page__view__findpost__p__290747]

'''Q. How do I make a good looking waterfall?'''

'''A.''' There's a discussion about this in this thread [http://forums.thedarkmod.com/topic/11901-waterfalls/page__pid__303963#entry303963]. For a small waterfall, a white foamy particle effect raining down by itself looks good. You can copy Bikerdude's example from St. Alban's Cathedral. [http://www.youtube.com/watch?v=gIrZDpc1m68]. For a bigger waterfall, people talked about a combination of a flowing vertical water block with the foamy particle effect towards the bottom.

'''Q. How do I make a nice little pond.'''

'''A.''' See this wiki entry [[How_to_create_a_pond]]. This thread [http://forums.thedarkmod.com/topic/14647-how-can-i-make-a-realistic-looking-pond/page__view__findpost__p__308916] has discussion on it.

== Patches! ==

'''Q. Is it possible to split patches?'''

'''A.''' See this tutorial on it [[Patch_Splitting_-_Basic_Tutorial]].

'''Q. How do I bend patches?'''

'''A.''' See the instructions at [[Patches#Bending_Patches.2C_Curves.2C_L-shapes.2C_etc]] (Here's another small tutorial in a post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__277350].)

'''Q. I want to use a patch to round off a corner.'''

'''A.''' See this part of the Patch wiki page [[Patches#Round_and_Soft]].

'''Q. How can I make a perfect circle with patches?'''

'''A.''' Select verts of 4 corners, select the "rotate and scale" tool, and use the value "0.9428" to scale "up" (actually down) in the 2 corresponding axis of the scale tool. See this post [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__279356].

'''Q. How do I make a dome or sphere?'''

'''A.''' Make a cone patch and drag down the top vertex to form a dome. Invert the matrix if you want an internal dome or thicken if you want it to be visible inside and out. A sphere is just two of these stuck together. Also tweak the tesselation in patch inspector if it is too chunky. You can have fun with the textures though; try fit. If you totally flatten the dome you have a disc which can produce some nice texture effects, eg, the marble floor centrepiece or a round rug. Drag a side to make it oval. See this post for a picture [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__233107].

'''Q. How do you align a texture on a curved patch?'''

'''A.''' When you want to align properly texture to curved patch like this one in the image [NB: image is missing], divide a brush according to the angle of the patch then use it's shader for your purpose. ... I made it with one edge is at one end of the curved patch and the other edge is at the other end. It gets distortions without this way.

== Events and SFX ==

'''Q. How do I trigger an earthquake event?'''

'''A.''' Earthquakes can be done with a speaker. Just use the spawnarg "s_shakes" "1" on the speaker, and the screen will shake violently however loud the sound gets.

'''Q. How do I emulate something like a blizzard or dust storm?'''

'''A.''' Doom3 made a dust storm area, and the same method can be used to make a blizzard, so it's possible. I'm leaving this here to look up instructions for future reference.

'''Q. How do I make the screen fade to black (or some other color), or from black back to the game.'''

'''A.''' Trigger a script with the functions fadeIn [http://www.modwiki.net/wiki/FadeIn_%28script_event%29], fadeOut [http://www.modwiki.net/wiki/FadeOut_%28script_event%29], or FadeTo [http://www.modwiki.net/wiki/FadeTo_%28script_event%29].

== Textures ==

'''Q. What's a quick way to align textures between two surfaces?'''

'''A.''' For two brushes, select the first surface, then '''edit --> copy shader''', then click on the second surface and '''edit --> paste shader'''. This will seamlessly match the 2nd surface to the texture of the 1st. DR also comes with a useful tool for texture alignment, [[Texture_Tool]], which you bring up with Ctrl+Alt+T. If it's textures on two patches, you can follow these directions: [http://forums.thedarkmod.com/topic/14034-tutorial-for-road-creation/page__view__findpost__p__294114]

'''Q. How do I randomize the position of textures on multiple brushes, e.g., for a row of stairs or pillars all with the same texture that I want to look different?'''

'''A.''' Select multiple faces and in the surface inspector, press the natural button once you set the scale properly.

'''Q. Can I blend textures?'''

'''A.''' Yes. This is particularly good for dirtying some textures up by blending in a grime texture. You can blend textures with a custom material file. Link to instructions coming. Also see the entry for [[Basic_Material_File]].

'''Q. How about blending texture transitions so there isn't a sharp seam, e.g., for a dirt path in grass?'''

'''A1.''' DR comes with grass edge transition decal patches to overlay the hard edges. Read how to set it up here [[Grass_Edges]], or a more detailed tutorial on making roads here [[Roads]].

'''A2.''' In NHAT blended terrain was made from patches broken into segments then exported as ASE models. Then the models were vertex painted in Blender and imported back into Dark Radiant. See this tutorial [[DrVertexBlend_(tutorial)]].

'''Q. How do I set the color for some textures (like glowing mushrooms) and make lightbulbs go dark when turned off?

'''A.''' "Colorme" textures allow you to set the color with a spawnarg. So e.g. for colored mushrooms, choose a colorme skin with the spawnarg like "skin" "mushroom_selflit_green_colorme" and choose the color with a spawnarg like "_color" "0.24 0.50 0.40" (where the value is the RGB values you want). For lightbulbs you can trigger a colorme texture switch with the lightswitch (so it switches between "lit up" and "black"). Instructions on that coming.

'''Q. What's a fast way to put different textures on a lot of objects?'''

'''A.''' 1. Click the mouse wheel on the texture to copy it. 2. To paste it naturally (i.e., in a random position): shift+mousewheel click. 3. To just paste it: ctrl+mousewheel click.

'''Q. Can you tile a texture a specific number of times to fit a surface?'''

'''A.''' When you want to tile a texture a certain number of times, enter the values 1/X and 1/Y (you need to compute them in your head) in the little boxes in the surface inspector, then press "Fit". It will tile your texture horizontally X times and vertically Y times. You can also enter things like "2" and "1" and get a texture that only occupies half of the width. You can then use the "Right" or "Left" buttons to align it quickly at the ends. Pro-tip: Press CTRL+ALT+T to open the texture tool, it allows super quick aligning of textures on patches. Esp. useful for decals where the decal texture consists of multiple decals.

== Readables & GUIs ==

'''Q. How do I put custom art in a book or scroll, like a picture?'''

'''A.''' Use a custom .gui. Here's a rough idea to get you started [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__263836]. I'll try to put better instructions in later.

'''Q. How do I trigger a text message to pop up and say something?'''

'''A.''' Create an entity: darkmod > targets > atdm:gui_message and give it the properties/values that you want. Popups will explain each one. You can target it with a triggering entity or trigger it from a script or any other triggering mechanism. An example is here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__256592]

== Lighting and Sound ==

'''Q. How do I add music or ambient sounds?''' '''Q. Can I dynamically adjust the ambient lighting?'''

'''A.''' For both of these things, check out the article for [[Location Settings]]

{{editing|sort=Editing FAQ (Troubleshooting & How-To)}} {{tutorial-editing|sort=Editing FAQ (Troubleshooting & How-To)}} {{darkradiant|sort=Editing FAQ (Troubleshooting & How-To)}}

'''Q. How do I set up Reverb (EAX) settings for my rooms? (E.g., the echo of a large hall, etc.)'''

'''A.''' Create a text file and name it <mapname>.eax; place it in your .pk4 with your .map file; and in it create entries by location name with the values you want for that location. See this wiki entry to see the format & values [[Setting_Reverb_Data_of_Rooms_(EAX)]].

Editing FAQ - Troubleshooting & How-To

2013-11-09T01:08:04Z

Demagogue: /* World Building */

Below are some common issues and questions mappers have had in the Editor's Guild forum with common solutions. Some of this assumes you've already gone through the [[A_-_Z_Beginner_Full_Guide_Start_Here!]], [[Startpack_Mappers'_Guide]], and [[Dark_Radiant_Must_Know_Basic_Intro]]. (If you know a FAQ not here and worth going in this list, and you know the right answer(!), or you can improve an existing answer, please add it if you have edit control or PM it to a team-member if you don't.)

= Troubleshooting FAQ =

== Rendering & VisPortal Issues ==

'''Q. Some of my brushes have disappeared or turned black and won't render.'''

'''A.''' This can happen when two touching brushes around the seam are not perfectly flush with one another and the rendering hiccups for those brushes & brushes behind it, either there's a tiny wedge or overlap or gap or weird angle between them. The usual solution is to make sure the brushes are snapped to the grid and perfectly flush against one another, or more generally to simplify the brushwork around the seam of the disappearing brushes.

'''Q. My visportal is not showing up or not closing like it should (you can check this with by typing "r_showportals 1" in the console. The portal edge will show green when open and red when closed.).'''

'''A.''' A common reason for that is that the two areas separated by the portal are not hermetically sealed and there's an internal leak, either (1) there may be an unportaled gap between the two, possibly covered up by func_static (which do not seal) or possibly caused by an inadvertent hole created by the first FAQ question above, or (2) an internal leak can happen when all sides of the visportal are not buried in or flush against sealing brushes, and there's a gap between the visportal and brush, or possibly even a tiny gap just touching the visportal side is enough to break it. A way to check if there's an internal leak, and locating it if there is, is described here: [[Visportals#Trouble-shooting]]. Other reasons it might fail are also described there (such as accidentally changing a nodraw texture to something else).

'''Q. I can see other rooms behind a mirror (or any reflective surface) through it, instead of just a reflection.'''

'''A.''' The area behind a mirror should be in a separate leaf (visportaled area) behind a closed visportal so it doesn't render. This problem usually means the two areas aren't in separate leafs, the portal isn't closed, or there's an internal leak between the areas in front of and behind the mirror.

'''Q. Help! I'm having rendering & visPortal issues all over the place ... broken portals, sparkly lines, disappearing brushes, z-fighting, uneven walls, etc.'''

'''A.''' As a general piece of advice, messy brushwork leads to trouble one way or another. To keep your brushwork clean:
* keep snapped to the grid (Ctrl+G toggles) & stay away from small grid levels (Typing a number or Plus/Minus changes the grid scale; 8 is a good starting grid; staying at or above 2 or 4 is fine for most stuff; going below 1 is usually just for special situations).
* Make brush intersections perfectly flush.
* Stay away from unnecessary tiny brushes & wedges (leave detail work to func_statics; brushes are for closing off leafs and the void. Of course you can do fine detail work with brushes & convert them to a func_static).
* Don't use the "CGS Subtract" tool if it will shatter the brush into tiny slivers; use the cut tool instead (open by pushing "X").
* You can use patches for uneven geometry with square brushes underneath textured with caulk.
* When rotating geometry, avoid weird angles when you can (where vertexes end up off the grid), and for multi-brush structures, build the whole thing first *then* rotate it all together instead of rotating & placing each brush individually.
These aren't rules set in concrete if you want to do something special once in a while, but general rules of thumb that will make life a lot easier if you generally stick to them.

== Crashes and Warnings ==

'''Q. My map has a leak in it, but a pointfile either isn't generated or doesn't make sense. (A pointfile is generated when dmap occurs and there's a leak, then you open DarkRadient and click File>Pointfile to see it. It normally runs a red line that ends in the void, pointing out the leak).'''

'''A.''' Make sure a gap isn't covered up with func_statics. If the origin of a model is in the void it will also cause a leak with a non-sense pointfile. Read more on the [[Leaking maps]] page.

'''Q. How do I scroll up through the console output to see what a problem was during dmap or map or in-game?'''

'''A.''' Use the mouse wheel or PageUp/Down to scroll through the console.

'''Q. I'm getting an error message "warning: aas is out of date" once my map has loaded. What does it mean and what do I do?'''

'''A.''' The AAS is for AI pathfinding. It usually means you changed brushwork and started a map without dmapping first. The solution is to dmap. If you dmap and still get the warning, delete your .aasxx, .proc, and .cm files in the maps folder and dmap again. If you're still getting a warning, then it could be a sign that something in your map is breaking the AAS pathfinding. Try monsterclipping tricky areas for the AI to path (like around objects and uneven ground) or clean up messy brushwork that might break the dmapping like sliver brushes.

'''Q. I have encountered a malloc failure error while dmapping my level. Instead of finishing with the dmap operation, it crashes midway with an error message.'''

'''A1.''' One solution to this is given in the Dmap wiki entry here: [[Dmap#Malloc_Errors]].

'''A2.''' This is what I've done to fix this exact issue. Open the map in DarkRadiant, select everything, copy to clipboard. Open another instance of DarkRadiant and paste from clipboard. Save as new filename and dmap new file and that has worked 3 times now with random unresolvable crashes.

'''A3.''' GC and I have found correlations between visportalling and mAlloc errors. Time to re-arrange your visportals. In NHAT, we had many malloc problems until we retooled how each area was portaled. Originally, every other visleaf had tons of entities, while half had hardly any. That's not neccessarily bad, but it strains the dmapper when one or two visleafs are cluttered with entities that really bloat your mapname.proc file. We added a few more portals to even out entity distribution, and dmap was happy again.

== Performance Issues ==

'''Q. My map is so slow. How do I improve performance?'''

'''A.''' See these wiki entry: [[Performance:_Essential_Must-Knows]]. Tips include:
* Reduce AI [[Pathfinding]] with Monsterclipping helps performance, simplifying complex bumpy surfaces into 1 smooth monsterclipped surface, or excluding entire surfaces AI should never walk on, like detail brushwork or some roofs.
* Use [[Interleaved_Thinking_optimization]]. Reducing AI think-time helps performance quite a bit.
* break-up long lines of sight,
* improve visportal & leaf placement (so less architecture is rendered at a time),
* use fewer AI,
* convert ornamental brushwork into func_static,
* reduce the overlap of light sources on surfaces by adjusting their placement & reducing their light-radius. (Every time a new light hits a surface, it's another render pass. So 4 lights hitting a surface processes it 4 times. If only 1 light hit it, its lighting is processed in 1/4 the time), and
* set objects and lights to "noshadow" if it won't be noticable to the player or affect gameplay (possibly in combination with low-poly shadow meshes or shadowy decals. Note that "noshadow" has two jobs. Put on lights, it means that light will cast no shadows on any object. Put on objects, it means that object will not cast a shadow from any light.)

There are also lots of other tricks out there if you check around the forums, including more advanced & optional tricks such as using the [[LOD]] system or [[SEED]] system, or even crazier tricks (cross-leaf func_statics, skybox architecture, Strombine lighting, Camera Cubemapped Visportal Patches, lots of crazy tricks out there), that you don't have to worry about if you're a new mapper but you can ask us about or search for in the forum if you're curious. Generally speaking there are pros and cons trade-offs between performance & dazzle for many things (like lights or visportal placement); so it's good to think about the best performance-dazzle balance for your scene. E.g, lots of highpoly brushwork, lights, & AI can look good in a small or medium room, but may not be worth the performance hit in a big courtyard, and try to find ways to get better performance "for free" without the player noticing anything missing, like smart use of noshadows, monsterclips, and interleaved thinking distances.

== Gameplay Issues that Mappers sometimes Overlook ==

'''Below is a list of common gameplay issues that players sometimes complain about and that mappers & testers sometimes overlook or should at least be aware of.'''

- Players find it very difficult to frob objects (loot, keys, readables) when the frob distance is set too short or the space is awkward (like in a drawer or up on a wall, etc). In testing, please double-check that every frobable object is easy to frob from a comfortable place, and increase the frob distance if it's not, erring on the side of more space. (See the question on making frobbing easier under "Handling Objects" below for more information.)

- Objects can get stuck into brushwork while moving them around.

- Players can get stuck in narrow spaces and can't mantle out, so try to avoid this kind of geometry if possible.

- A very low ceiling can prevent hitting AI with a BJ, so try to avoid it when AI are around.

- Make sure AI have a flee path.

- Some players would like the ability to drop used keys and other inventory items, done by turning the can_be_dropped property to true, unless for gameplay reasons you don't want to.

- Some players don't like long readables that don't get to the point. At least be conscious of how your readables read to a player.

- Think about how you want to handle non-functioning doors (or other "unnatural" situations like windows that can open) in a way that visually or fairly communicates to the player that something is special about this door or window, but isn't too immersion breaking either.

== Issues with Objects ==

'''Q. My streetlight, candle, lamp, light-creating object, causes a weird shadow I want to get rid of.'''

'''A.''' Put the spawnarg "noshadows" "1" on the offending object.

== AI Issues ==

'''Q. My AI will not pass through a visportal no matter how I set up the path nodes.'''

'''A.''' Check that the sides of the visportal use the nodraw texture (except for the portal-face itself of course).

'''Q. How do you get AI to walk on complex terrain patches or func_statics?'''

'''A.''' You can always lay down invisible monsterclip brushes and the AI can walk on it. Overlay with a brush with a "material" clip texture so it causes the right sound for footsteps.'''

== Problems with Patches ==

'''Q. I have 2 curved patches and they're not aligning. What do I do?'''

'''A.''' See this wiki page [[Patch_Troubleshooter]].

'''Q. My patch is rendering strangely, like fractured into slivers.'''

'''A.''' See this wiki page [[Patch_Troubleshooter]].

== Issues with Lighting & Sound ==

'''Q. Some of the parallel lights I use for moonlight aren't giving off any light.'''

'''A.''' This is a known problem with parallel lights. For some reason in some arrangements you get no light at all. Just fiddle with it a bit - move it slightly, change the radii, move the vertex a bit - and it should suddenly work. Once you've got it working then it's stable. Likely the code chokes on certain values in its calculations. ... Also, to help optimize your moonlight, you should adjust the radius so it's only as big as it needs to be. You may also want to move the actual position of the little moon cube in the skybox to match the parallel light (and make sure to fix the texture on it if you mess it up - hint: lock textures before moving cube to make it easy)

= General How-To Editing FAQ =

== Dark Radient Questions ==

'''Q. How do I see all the default properties already on an object?'''

'''A.''' In the entity inspector there's a checkbox near the top that says "Show Inherited Properties". Click that box.

'''Q. What are some basic units, scales, limits, maxs, and mins of various things when editing?'''

'''A.''' A list of all these things is here: [[Limits,_Max,_Min,_Stats,_etc]].

'''Q. Can I manipulate brushes to resize and reshape them?'''

'''A.''' Yes. In DarkRadient you can select a brush and push "V" to select verticies to drag and resize, "E" to select edge(s) to drag and resize, and "F" to select face(s) to drag and resize. "Ctrl+#" makes a selected brush be #-sided. You can also use the Brush>Prism and Brush>Cone to convert a brush to those shapes.

'''Q. What are some common DR shortcut commands?'''

'''A.'''
* "H" hides selected items.
* "I" inverts selected.
* "Ctrl+I" inverts a patch's normal.
* "J" brings up entity list.
* "Ctrl+K" makes 1st-selected-entity "target" 2nd-selected-entity.
* "L" brings up light inspector.
* "Ctrl+L" brings up the Layers menu.
* "N" brings up entity inspector.
* "T" brings up texture browser.
* "X" go into clipper mode.
* Brush manipulation modes: are "R" rotate brush, "Q" free-move & resize, "W" translate-move.

'''Q. How do I make my own shortcut key commands?'''

'''A.''' Under the Edit menu, at the bottom is "Keyboard Shortcuts" which allows you to set your own shortcuts.

'''Q. I screwed something up! What do I do?!'''

'''A.''' Ctrl+Z undos. Ctrl+Y redos.

'''Q. Is there a way to organize & simplify building, so I can build one section at a time without other sections getting in the way?'''

'''A.''' DR has a [[Layers]] function that lets you build one "layer" at a time (open with ctrl+L or View>Layers). It also improves DR performance, which is handy as the map gets bigger.

'''Q. How do I set up things like the pre-game shop, the player inventory, and an in-game map?'''

'''A.''' All these things are described in the Startpack Mappers' Guide: [[Startpack_Mappers'_Guide#Ammo.2C_Weapons.2C_Player_Tools.2C_Start_Inventory]], [[Startpack_Mappers'_Guide#Purchase_Shop]], [[Startpack_Mappers'_Guide#Adding_an_In-game_Map_to_your_FM]]

'''Q. How do I put spawnargs on def_attached entities?'''

'''A.''' You can put spawnargs on def_attached entities by using the spawnarg "set SPAWNARGNAME on ATTACHMENTNAME" "value" on the base entity. Here's an example of setting a color property on a flame attachment to a torch "set _color on flame" "0.2 0.2 0.9". Read more here [[Combined_light_entities#Setting_spawnargs]].

'''Q. What's an easy way to find materials in DR?'''

'''A.''' Tip to help find materials in Dark Radiant's materials browser:
# Point to Textures (or any tree).
# Shift + Right key to fully open the tree.
# Type the key letters of what you want to find.
# Up/down arrows to go to next/previous occurrence.
# Esc to get out of input field.
Oh yeah, avoid F3 because that is likely to switch to render mode which in my case crashes DR (but may not if the map is small).

'''Q. How do I make an N-sided brush?'''

'''A.''' A quick way to make an N-sided brush is to highlight the brush and push cntl+N (N being the number of sides for the top face). So if you want a 5-sided brush, highlight it and push cntl+5. But the best way to get the walls of a multi-sided brush to line up seamlessly is still to use the clipper-tool and precisely cut off a slice. (And don't use CSG Subtract unless you know what you're doing and aren't creating a million splinters!)

== Console Questions ==

'''Q. How do I open the console?'''

'''A.''' Open the console with ctrl+alt+~ in a normal game, and just ~ when playing through "map".

'''Q. How do I scroll through the console output?'''

'''A.''' Use the mouse wheel or PageUp/PageDown.

'''Q.What's a list of all the Doom3 Console Commands and CVars?'''

'''A.''' A list of all commands & Cvars is here [http://www.doomwadstation.com/doom3/console/]. Darkmod Cvars are listed here [[Cvars_in_The_Dark_Mod]].

'''Q. What are some *useful* console commands and cvars for editing?'''

'''A.''' Here's one list: [[Console_Useful_Controls]]. Here's a list more tailored to mapping:

Commands:
"'''dmap <name>'''" compiles a map,
"'''give <name>'''" gives the player an item,
"'''god'''" player cannot be harmed,
"'''killmonsters'''" takes out all AI
"'''map <name>'''" loads a map to play,
"'''noclip'''" lets the player go through objects and walls,
"'''notarget'''" let's the player be invisible to AI,
"'''reloadDecls'''" will reload material defs without having to re-start TDM,
"'''reloadimages'''" does the same for lights and
"'''reloadSurface'''" for surfaces,
"'''saveRagdolls'''" saves the positions of all ragdolls to the .map file (see the FAQ under Handling AI),
"'''teleport <name>'''" teleports the player to an entity.
"'''tdm_show_loot'''" Shows loot.
"'''spawn <name>'''" spawns an entity:
spawn atdm:weapon_blackjack
spawn atdm:weapon_shortsword
spawn atdm:ammo_broadhead
spawn atdm:ammo_firearrow
spawn atdm:ammo_gasarrow
spawn atdm:ammo_mossarrow
spawn atdm:ammo_noisemaker
spawn atdm:ammo_ropearrow
spawn atdm:ammo_waterarrow
Append "inv_ammo_amount 50" to any of the above to spawn 50 arrows at once: spawn atdm:ammo_broadhead inv_ammo_amount 50
Cvars (1 turns on, 0 turns off, unless otherwise noted):
"'''com_showFPS 1'''",
"'''r_showLightCount 1'''" (colors shows the number of lights hitting a surface, black = 0, red = 1, blue = 2... etc),
"'''r_showPortals 1'''" (red=closed,green=open) If your portals dont show up they are most likely not sealing.
"'''r_showTris n'''" (n=1) Shows tris rendered directly, (n=2) shows overdrawn tri's, (n=3) shows all tri's, direct and indirect.

== Objectives ==

'''Q. How do I set up a put-object-here objective?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__182924]

'''Q. How do I set up a "ghosting" objective (e.g., you are busted if you are seen.)'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__204695]

== Handling Objects ==

'''Q. How do I attach a door handle to a door?'''

'''A.''' Just position the handle and input "bind" and the door entity ID/name as a spawnarg.

'''Q. How do I make an object into loot?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__182921]

'''Q. How do I make an entity frobable?'''

'''A.''' See the entry for [[Making an Entity frobable]].

'''Q. Ok it's frobable, but doesn't fall or move. How do I make an entity act like a world object?'''

'''A.''' You need to make the object a moveable, see [[Moveables]].

'''Q. How do I get a lever or button to open a door?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__212036]

'''Q. How do I put some text on a sign or wall?'''

'''A.''' You can use this method [http://forums.thedarkmod.com/topic/11159-add-text-to-your-signs-signposts-walls-etc/]

'''Q. How do I bind something to a rope (like a body) so it doesn't fall?'''

'''A.''' Dynamic ropes are unreliable, so it's good to use a func_static like a chain or make a func_static rope from a cylinder brush. For a ragdoll, place the ragdoll so he clips into the func_static. You need to bind the ragdoll to the chain (so the spawnarg is on the ragdoll), with "bind" "func_static_...", where func_static_... is the chain. Or, through DR, you can just select the entity you want to attach (the ragdoll), then also select the thing you want to attach it to (the chain), and in the menus select "Entity" - "Bind selected entities". But it's been reported the clipping does the job, not binding. See this link [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__221262]

'''Q. How do I make something switch from frobable to unfrobable like a used lever, or unfrobable to frobable like contents in a chest or drawer you don't want frobable until it's open?'''

'''A.''' Make a brush around the object with a clip texture and convert it to an atdm:target_set_frobable entity, with the property "start_frobable" 1 or 0 (which mean true or false) depending on your case (it affects everything inside), and a triggering entity, such as the lever or the chest itself, that targets the set_frobable entity that triggers the switch when it's frobbed. For the record, you can also switch the frobability of an object in a script with the command: '''$<entityname>.setFrobable(n);''', where n is "1" to make it frobable and "0" for unfrobable.

'''Q. How do I make breakable glass?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__222734]. You basically convert your glass brush to a func_fracture entity and set the "health" spawnarg to the value you want the glass to break at.

'''Q. What about an object that gets increasingly damaged-looking as you hit it?'''

'''A.''' Use a func_damagable entity, which replaces its model and/or shader with increasingly "damaged" versions (as many stages as you like) when its health goes below the threshold you set with the "health" spawnarg, and you can use "target" to trigger something when damage occurs (such as a sound effect or event). See here for details on the spawnargs involved in setting it up: [http://www.modwiki.net/wiki/Func_damagable_(entity)]

'''Q. How do I make an object that you can frob and it does something or something happens?'''

'''A.''' If it's an object you made from patches or brushes, make it into a frobable func_static, or if it's already a func_static, make sure it's frobable ([[Making an Entity frobable]]). Then give it a Frob response whose effect is a trigger, and give it a "target" spawnarg to the entity that causes your effect when triggered.

'''Q. Can a lever or button target multiple entities?'''

'''A.''' Yes! Use the spawnargs "target1", "target2", "target3", etc, with each entity-target as a value. A quicker way is to use the keyboard shortcut Ctrl+K. Select the button or lever, then select the target-entity and hit Ctrl+K. De-select the target-entity then select the next one, hit Ctrl+K again. Each time adds a new target to the switch. (Many other spawnargs allow you to have multiple entries by numbering them, such as bind and def_attach.)

'''Q. How do I make a rotating entity, like a fan?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__242385]

'''Q. How do I make objects non-solid so they still render but the player can walk through them?'''

'''A.''' Add the spawnarg: noclipmodel 1 to turn them into non-solids.

'''Q. How do I make a firefly or will-o-wisp, basically a glowing ball that floats around?'''

'''A.''' This is a rough explanation to help you get started. A firefly is a func_emitter. Click the model property then use the button bottom right to select a suitable particle effect, possibly tdm_glare_lamp_01.prt. Bind to something invisible that will move it along a path, typically a func_mover with nurb curves used as the path. A tutorial for setting up nurb curves is here [http://www.doom3world.org/phpbb2/viewtopic.php?t=5123].

'''Q. How do I trigger an event from something in the player's inventory?'''

'''A.''' give the object a "target" to trigger and also the property/value: scriptobject InvTriggerScript. If your object does not already go in the inventory then use the entity: items > custom > atdm:moveable_custom_item. If you get a collision model error then ask on the forums for help (or read the wiki entry for [[Moveables]]).

'''Q. How do I teleport an entity?'''

'''A.''' Use targets/atdm:teleport. See this wiki page [[Teleporting_entities]].

'''Q. How do I make a custom inventory item with its own inventory icon graphic?'''

'''A.''' See this entry [[A_-_Z_Beginner_Full_Guide_Page_6#Special_Items]] for setting the inventory category, loot type, inventory name and inventory icon. To repeat the instructions for a custom icon: on the object put the property "inv_icon" with a value "guis/assets/hud/inventory_icons/<name>.tga" (substitute whatever name you gave it for <name>), and package your .pk4 to put your image file in that relative location. You can also see other inventory_icons there and can use an existing one, or package your .pk4 to replace an existing one with your custom one. A method for making an inventory icon is described here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__259172] (be sure to use an alpha channel to make the background transparent, tutorial: [http://www.axialis.com/tutorials/tutorial-misc001.html]).

'''Q. How do make an object that's hard to frob easier to frob?'''

'''A.''' One easy way is to add this property: frobbox_size 5. If it's still hard, see this post for other things you can do. [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__228245]

'''Q. How do I make a candle you can pinch to go out?'''

'''A.''' I made a bunch of pinchable non-moveable candles into my WIP like this:
# Make a func_static candlestick. place light source entity candleflame on it.
# Give the candlestick "frobable 1."
# Give the candlestick S&R response frob, extinguish light and candleflame name.
# You can optionally add another response frob to trigger a speaker with a "snuff" sound effect.
# Done.
You can copy the entity bunch around and all the params should update correctly for the new replica. Frobbing will not relight it: the player needs to relit them with a flame source.

== Handling AI ==

'''Q. How do I make sure a guard can unlock a door?'''

'''A.''' There are a few different ways, explained here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__217915]

'''Q. How do I attach a key or purse to an AI's belt, or similar kinds of attachments?'''

'''A.''' The easiest way is with "bind". Place the key or purse around the belt area where you want it, sticking a little farther out than usual, and rotate it as desired. On the key add the property "bind" with the value of the AI's entity-ID or name, then the property "bindToJoint" with the value "leftHips_dummy" or "rightHips_dummy" as needed. For attaching things in other places (like a ring or hat or necklace), it's the same general principle but you should look up the joint to attach to. A list of all the joint names is here: [[BindToJoint]]. See this wiki entry for more info [[Attaching_Items]]. For another method using def_attach see [[Attaching_Props_to_AI]], and this post for an example of the spawnargs involved [http://forums.thedarkmod.com/topic/13084-ai-attach-keys/page__view__findpost__p__276064]. The issue with def_attach is that the attached thing spawns at its own rotation angle, which might not look great and is tricky to change (if you insist, see [[AI_Attachment_Ingame_Editing]] and [[Cvars_in_The_Dark_Mod#Attachment_related]]). With bind you just place and "bind", and it stays where you put it.

'''Q. What about other kinds of attachments where special animations are involved, like torches and weapons?'''

'''A.''' For these you want to use Def_Attach. See this wiki entry [[Attaching_Props_to_AI]]. For heads & weapons specifically see this wiki entry [[Adding_Heads_and_Weapons_to_AI]]. (You can set spawnargs on the def_attached entities with the method described here [[Combined_light_entities#Setting_spawnargs]].)

'''Q. How do I mute an AI?'''

'''A.''' Give the AI the spawnarg: def_vocal_set atdm:ai_vocal_set_mute. If you only want to mute some barks, you'll have to modify the AI's .def file by hand, taking or commenting out the barks you don't want, and packaging the new def file in your mission's pk4. For coughing and animation based barks, see this post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__224558]

'''Q. Can I hide an AI until I trigger him?'''

'''A.''' No, the spawnarg "hide" doesn't work well with AI (they're made invisible, but still audibly there). Put the AI in a blueroom and use a teleport instead, or a teleporting script command. See the wiki entry for [[Teleporting_entities]]. Note, after teleporting an AI, pathing becomes a problem for it. See this post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__280818] and the previous posts on this issue to make sure the AI can path properly after a teleport.

'''Q. How do I manage AI teams, who is a friend, enemy and neutral?'''

'''A.''' To set the teams, see [[Relations]]. If you want to trigger a change in team with a script, see [[AI_Relations_(Scripting)]]. Another method to switch AI teams using S&R (stim & response) is described here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__256126] and see the entry [[Stim/Response]].

'''Q. How do I make an AI play an animation when I want?'''

'''A.''' Instructions are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__253169]. There may be other ways possible.

'''Q. How do I set or change the health of AI?'''

'''A.''' AI use the spawnarg "health" to set their hit points. To change it in-game, use a script and the function "setHealth".

'''Q. How do I pose ragdolls so they look naturally placed?'''

'''A.''' Save a backup, pose all the ragdolls in-game, then use the console command saveRagdolls which saves their positions to the .map file. cf. [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__265650].

'''Q. How do I make a scene of AI playing cards?'''

'''A.''' Probably the easiest thing to do is load the prefab (under AI), place it, and adjust it how you want.

'''Q. How do I make an AI frob something?'''

'''A.''' To get an AI to frob something, eg, a lever (doesn't work to pick up and carry) create a path_interact entity. You can include it in a normal pathing patrol. Give it these 2 spawnargs: ent <name of entity you want the AI to frob>; target <next path entity (if any)>. Note that the AI won't walk to this entity; you have to use a path_corner to get him where you want then target to the path_interact to get him to frob.

'''Q. How do I make an AI catch fire?'''

'''A.''' You can bind some unlit fires to an NPC (like a zombie) and shoot it when a fire arrow, he'll erupt in flames, but the flames won't damage him. You could also light him with a candle. I'd bet theres some way to make that actually kill the creature, or at least cause it damage. ... One improvement suggestion: When the the light gets the fire stim, target a trigger multiple, which delays for a 120-240 seconds and then turns the fire off. You could make the fire damaging by starting a trigger timer which applies the stim damage to the target every few seconds. Remember to switch off the timer when the flames are doused.

'''Q. How do I keep an AI ragdoll from sinking into the bed model, e.g., if he's KO'd?'''

'''A.''' I found one way to keep [an unconscious/dead ragdoll body] from sinking into the model below it is to use a platform of nodraw_solid underneath the body. You should be able to place such a brush within the bed model and test it with a ragdoll on the bed. Adjust it's top surface height until the body lays just on top of the bed (then delete the ragdoll)... then a blackjacked AI should be able to stay on top of the bed like the ragdoll did.

== The Player ==

'''Q. How do I do things with the player's inventory, like trigger an inventory item to be deleted, or an item to be added to the inventory, or one item being replaced with another item?'''

'''A.''' You can do all these things with a script (read [[A_Beginner's_Guide_to_Scripting]] and the scripting FAQ below to learn about scripting). Have your triggering mechanism trigger a target_callscriptfunction entity which calls a custom script, then use the appropriate script command in the script on $player1. A list of the commands is here [[Inventory#Scriptsupport]].
Useful commands are (replacing the "Item" variables with the item ID):
* '''$player1.addInvItem(inv_item);''' and
* '''$player1.replaceInvItem(oldItem, newItem);''' (note: If <newItem> is the $null_entity, <oldItem> is just removed and no replacement happens.)
For example, to remove a key from the player's inventory, use a command like: '''$player1.replaceInvItem ($key, $null_entity);'''

'''Q. How do I teleport the player?'''

'''A.''' Use base > info_player_teleport. Give it the spawnarg and value: target info_player_start_1. Give it the spawnarg: angle with a value if you want to force the player to turn to face a particular direction.

'''Q. How can I simulate a crawl for the player to pass under things like tables that he couldn't normally do?'''

'''A.''' See this post [[http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__229174]]

== Scripting ==

'''Q. How do I make a custom script?'''

'''A.''' First read [[A_Beginner's_Guide_to_Scripting]], [[Scripting_basics]], and [[My_first_map_script]] to learn the basics of scripting. You write a custom script as a text file named <mapname>.script and packaged in your .pk4 in the same place as your .map file. Inside it you make your own script object in the format the Beginner's Guide gives you, usually looking like '''void MyScript() { code goes here }'''. Then the game can "call" "threads" of that "script object" that will run until they end or are killed, so you can have more than one thread running of the same object concurrently. If you want multiple script objects, put them all in your <mapname>.script file and the game-engine will find them. You run scripts by the object name, not the file name.

'''Q. How do I run a script in-game?'''

'''A.''' A few common ways of calling a script object thread in-game are
# creating a target_callscriptfunction entity with the spawnarg: "call" "<name of your script object>", then creating some other entity (such as a button or trigger brush) that "targets" that entity;
# creating a button with the property "state_change_callback" "<script object>", which runs the script when pushed or triggered,
# Using [[Location_Settings#Script_calls]] to call a script when you enter or leave a location;
# triggering a script with the [[Objectives_Editor]] when you fulfill or fail an objective (possibly a hidden objective only for triggering the script);
# A script can call another thread in itself with the "thread" function; see the command in the link below.
# An entity can call a script when it spawns. Add a property/value either in the .def file or as a spawnarg on the entity: "ScriptEvent void <script object>(<parameters>);".
# The script "void main();" is always called at game start. So if you add code under that heading in your script file, it will run at game start.
There are other methods too. (Note, if you call a persistent script, i.e., it runs all game, be especially sure to avoid performance hits, or make it non-persistent if possible, that is, you "kill" it at some point in the game so it doesn't hog resources..)

'''Q. What are script events (aka commands or functions)?'''

'''A.''' A script event is a pre-made object that does something for you, usually to some game item you specify, just when you write it in your code (like '''$item.eventX();''' does X to item). Sometimes it wants parameters or arguments to run (the stuff in parentheses) and will give an error if you don't put the arguments in the parentheses in exactly the way it wants, with the right number of them & right data types, etc. And some of them return values too, especially the "get" functions, which are handed over to a variable (e.g., '''X = getValue();''', now X has the value. If X is an entity, you can even act on X as if it's the entity itself. Just be sure the data type of X and Value are the same, e.g. float, or string, or entity, etc, or you'll get an error).

'''Q. What are some common or useful script events for editing?'''

'''A.''' A list of all Doom3 and TDM script events are listed on this wiki page [[TDM_Script_Reference]], including the proper syntax (or this page, but it's down now: [http://www.modwiki.net/wiki/Script_events_%28Doom_3%29]), or also these two files in your Dark Mod folder (open with a text editor): scripts/doom_events.script, scripts/tdm_events.script. Note that TDM has some of its own script events, like setFrobable (in the tdm_events.script list).

A quick short list of common or useful script events good for editing is here: [[Script_Events_User-Friendly_List]], with syntax and description, and including TDM events. It doesn't list all script events and all details, just common & useful ones for actual mapping IMO. If you want the full list, use the TDM_Script_Reference link I gave above.

== World Building ==

'''Q. What's a good way to make caves?'''

'''A.''' Some tips are here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__204909] & [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__289484] Instructions for quick-cavern pattern building is here [http://forums.thedarkmod.com/topic/14469-quick-caverns-recipe/page__view__findpost__p__304250]

'''Q. How do I make a good looking roof using clean brushwork, including with an attic inside?'''

'''A.''' Here are descriptions of method that all use a similar trick [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__325945], [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__325944], [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__244109]. The trick is to "cut out" a roof from a square brush using the clipper tool. Avoid rotating brushes to make it by hand. Alternatively, use patches over a rectangular under-structure of BSP brushes, although this is not good if you want a portaled attic.

'''Q. What's a good way for making a city area that performs well?'''

'''A.''' Sotha gave a good method in this post. [http://forums.thedarkmod.com/topic/10003-so-what-are-you-working-on-right-now/page__view__findpost__p__312133]

'''Q. What's a good way for making a forest or a big outdoorsy area?'''

'''A.''' One good method is making large "rooms" in the shape of a big oval cylinder with very high natural-looking "rocky" & skybox walls and uneven ground using patches, filling it with trees and hiding some of the walls behind trees and greenery (you could also fill it with thick cylinder brushes of different sizes with bark texture to look like more trees, and place branches coming off them or to make a canopy), and possibly filling it with tons of grass (using [[SEED]]) and rocks and streams, with visportaled openings at "kiss points" in the walls to other large oval rooms at different orientations (maybe 2-5 connections per oval) so there's a dense web of interconnected forested rooms that (sort of) appear to be one big dense forest to the player. Some useful things to use are the [[Object_detail]], [[SEED]], and [[LOD]] systems. See the blueprint for the Thief 2 level Trail of Blood for a rough idea: [http://thief.wikia.com/wiki/T2_M10_Trail_of_Blood?file=T2_m10a_editor_colored.gif]. For good examples in Dark Radiant, look at the construction of mission 3 of No Honor Among Thieves ("No Honor Among Anyone") and Shadowhide's slenderman forest map. (Somebody post links to screenshots of those maps in DR, or remind me to.)

'''Q. How do I make uneven ground?'''

'''A.''' One method is by burying patches into the ground that stick out and make the ground lumpy as described here [http://forums.thedarkmod.com/topic/13338-newbie-mapper-tip-making-uneven-ground/page__view__findpost__p__274917]. For more encompassing unevenness, you can use much larger patches laid over square caulk brushes underneath that seal the leaf to make the entire ground uneven.

'''Q. How do I make a natural looking road where there isn't a sharp seam between the road material and grass but a nice fading transition?'''

'''A.''' See the Wiki page for [[Roads]].

'''Q. How do I make curved ceilings and archways?'''

'''A.''' Use patches. Here's a list of some good tutorials for this sort of thing [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__254764]. Also look at this wiki page [[Patches#Archways]].

'''Q. What's a way to get good-looking fog in my mission?'''

'''A.''' There are numerous values to make good fog. The setup for the fog from Fidcal's Heart mission is here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__248277].

'''Q. What are some tips to making a better looking map?'''

'''A.''' See this wiki entry [[10_Simple_Tricks_for_Better_Looking_Maps]].

'''Q. What's a good method or plan-of-action for building?'''

'''A.''' This is a matter of personal preference, but a method that professionals use is called the "stepwise refinement" method. It means you build the *entire* space of your mission first in rough blocks (so you have it all planned out first), then refine the whole thing in increasingly more detailed steps section by section, leaving the most fine detailing towards the end. It can help to use DR's Layer system to organize your building by sections too, without other sections interfering. Also, when you're drawing your map, think about arranging space into winding "rooms" (so there's no long lines of sight), even outside with tunnels, walls and skybox; and think about visPortal placement right at the start. Also think about the gameplay-performance balance of shadowing-lights & AI when thinking about placing them.

'''Q. How do I cleanly connect two brush edges meeting together, especially at a diagonal?'''

'''A.''' See this post [[http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__257111]].

'''Q. What's a method for building very fast & efficiently?'''

'''A.''' Sotha came up with "modular" approach where you build a few stock modules of architecture that you can combine to make a lot of geometry very quickly and efficiently. Here's his description: [http://forums.thedarkmod.com/topic/12833-sir-taffsalots-mapping-thread/page__view__findpost__p__290747]

'''Q. How do I make a good looking waterfall?'''

'''A.''' There's a discussion about this in this thread [http://forums.thedarkmod.com/topic/11901-waterfalls/page__pid__303963#entry303963]. For a small waterfall, a white foamy particle effect raining down by itself looks good. You can copy Bikerdude's example from St. Alban's Cathedral. [http://www.youtube.com/watch?v=gIrZDpc1m68]. For a bigger waterfall, people talked about a combination of a flowing vertical water block with the foamy particle effect towards the bottom.

'''Q. How do I make a nice little pond.'''

'''A.''' See this wiki entry [[How_to_create_a_pond]]. This thread [http://forums.thedarkmod.com/topic/14647-how-can-i-make-a-realistic-looking-pond/page__view__findpost__p__308916] has discussion on it.

== Patches! ==

'''Q. Is it possible to split patches?'''

'''A.''' See this tutorial on it [[Patch_Splitting_-_Basic_Tutorial]].

'''Q. How do I bend patches?'''

'''A.''' See the instructions at [[Patches#Bending_Patches.2C_Curves.2C_L-shapes.2C_etc]] (Here's another small tutorial in a post [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__277350].)

'''Q. I want to use a patch to round off a corner.'''

'''A.''' See this part of the Patch wiki page [[Patches#Round_and_Soft]].

'''Q. How can I make a perfect circle with patches?'''

'''A.''' Select verts of 4 corners, select the "rotate and scale" tool, and use the value "0.9428" to scale "up" (actually down) in the 2 corresponding axis of the scale tool. See this post [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__279356].

'''Q. How do I make a dome or sphere?'''

'''A.''' Make a cone patch and drag down the top vertex to form a dome. Invert the matrix if you want an internal dome or thicken if you want it to be visible inside and out. A sphere is just two of these stuck together. Also tweak the tesselation in patch inspector if it is too chunky. You can have fun with the textures though; try fit. If you totally flatten the dome you have a disc which can produce some nice texture effects, eg, the marble floor centrepiece or a round rug. Drag a side to make it oval. See this post for a picture [http://forums.thedarkmod.com/topic/11570-editing-tip-of-the-day/page__view__findpost__p__233107].

'''Q. How do you align a texture on a curved patch?'''

'''A.''' When you want to align properly texture to curved patch like this one in the image [NB: image is missing], divide a brush according to the angle of the patch then use it's shader for your purpose. ... I made it with one edge is at one end of the curved patch and the other edge is at the other end. It gets distortions without this way.

== Events and SFX ==

'''Q. How do I trigger an earthquake event?'''

'''A.''' Earthquakes can be done with a speaker. Just use the spawnarg "s_shakes" "1" on the speaker, and the screen will shake violently however loud the sound gets.

'''Q. How do I emulate something like a blizzard or dust storm?'''

'''A.''' Doom3 made a dust storm area, and the same method can be used to make a blizzard, so it's possible. I'm leaving this here to look up instructions for future reference.

'''Q. How do I make the screen fade to black (or some other color), or from black back to the game.'''

'''A.''' Trigger a script with the functions fadeIn [http://www.modwiki.net/wiki/FadeIn_%28script_event%29], fadeOut [http://www.modwiki.net/wiki/FadeOut_%28script_event%29], or FadeTo [http://www.modwiki.net/wiki/FadeTo_%28script_event%29].

== Textures ==

'''Q. What's a quick way to align textures between two surfaces?'''

'''A.''' For two brushes, select the first surface, then '''edit --> copy shader''', then click on the second surface and '''edit --> paste shader'''. This will seamlessly match the 2nd surface to the texture of the 1st. DR also comes with a useful tool for texture alignment, [[Texture_Tool]], which you bring up with Ctrl+Alt+T. If it's textures on two patches, you can follow these directions: [http://forums.thedarkmod.com/topic/14034-tutorial-for-road-creation/page__view__findpost__p__294114]

'''Q. How do I randomize the position of textures on multiple brushes, e.g., for a row of stairs or pillars all with the same texture that I want to look different?'''

'''A.''' Select multiple faces and in the surface inspector, press the natural button once you set the scale properly.

'''Q. Can I blend textures?'''

'''A.''' Yes. This is particularly good for dirtying some textures up by blending in a grime texture. You can blend textures with a custom material file. Link to instructions coming. Also see the entry for [[Basic_Material_File]].

'''Q. How about blending texture transitions so there isn't a sharp seam, e.g., for a dirt path in grass?'''

'''A1.''' DR comes with grass edge transition decal patches to overlay the hard edges. Read how to set it up here [[Grass_Edges]], or a more detailed tutorial on making roads here [[Roads]].

'''A2.''' In NHAT blended terrain was made from patches broken into segments then exported as ASE models. Then the models were vertex painted in Blender and imported back into Dark Radiant. See this tutorial [[DrVertexBlend_(tutorial)]].

'''Q. How do I set the color for some textures (like glowing mushrooms) and make lightbulbs go dark when turned off?

'''A.''' "Colorme" textures allow you to set the color with a spawnarg. So e.g. for colored mushrooms, choose a colorme skin with the spawnarg like "skin" "mushroom_selflit_green_colorme" and choose the color with a spawnarg like "_color" "0.24 0.50 0.40" (where the value is the RGB values you want). For lightbulbs you can trigger a colorme texture switch with the lightswitch (so it switches between "lit up" and "black"). Instructions on that coming.

'''Q. What's a fast way to put different textures on a lot of objects?'''

'''A.''' 1. Click the mouse wheel on the texture to copy it. 2. To paste it naturally (i.e., in a random position): shift+mousewheel click. 3. To just paste it: ctrl+mousewheel click.

'''Q. Can you tile a texture a specific number of times to fit a surface?'''

'''A.''' When you want to tile a texture a certain number of times, enter the values 1/X and 1/Y (you need to compute them in your head) in the little boxes in the surface inspector, then press "Fit". It will tile your texture horizontally X times and vertically Y times. You can also enter things like "2" and "1" and get a texture that only occupies half of the width. You can then use the "Right" or "Left" buttons to align it quickly at the ends. Pro-tip: Press CTRL+ALT+T to open the texture tool, it allows super quick aligning of textures on patches. Esp. useful for decals where the decal texture consists of multiple decals.

== Readables & GUIs ==

'''Q. How do I put custom art in a book or scroll, like a picture?'''

'''A.''' Use a custom .gui. Here's a rough idea to get you started [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__263836]. I'll try to put better instructions in later.

'''Q. How do I trigger a text message to pop up and say something?'''

'''A.''' Create an entity: darkmod > targets > atdm:gui_message and give it the properties/values that you want. Popups will explain each one. You can target it with a triggering entity or trigger it from a script or any other triggering mechanism. An example is here [http://forums.thedarkmod.com/topic/9082-newbie-darkradiant-questions/page__view__findpost__p__256592]

== Lighting and Sound ==

'''Q. How do I add music or ambient sounds?''' '''Q. Can I dynamically adjust the ambient lighting?'''

'''A.''' For both of these things, check out the article for [[Location Settings]]

{{editing|sort=Editing FAQ (Troubleshooting & How-To)}} {{tutorial-editing|sort=Editing FAQ (Troubleshooting & How-To)}} {{darkradiant|sort=Editing FAQ (Troubleshooting & How-To)}}

'''Q. How do I set up Reverb (EAX) settings for my rooms? (E.g., the echo of a large hall, etc.)'''

'''A.''' Create a text file and name it <mapname>.eax; place it in your .pk4 with your .map file; and in it create entries by location name with the values you want for that location. See this wiki entry to see the format & values [[Setting_Reverb_Data_of_Rooms_(EAX)]].