iddevnet/quake4/Tutorial_ScriptEntities.html

359 lines
24 KiB
HTML
Raw Normal View History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<meta name="robots" content="index,nofollow">
<title>Tutorial ScriptEntities - Quake 4 SDK Documentation</title>
<script type="text/javascript" src="wiki/common/js/common.js"></script>
<script type="text/javascript">
<!--// common functions
// We keep here the state of the search box
searchIsDisabled = false;
function searchChange(e) {
// Update search buttons status according to search box content.
// Ignore empty or whitespace search term.
var value = e.value.replace(/\s+/, '');
if (value == '' || searchIsDisabled) {
searchSetDisabled(true);
} else {
searchSetDisabled(false);
}
}
function searchSetDisabled(flag) {
// Enable or disable search
document.getElementById('fullsearch').disabled = flag;
document.getElementById('titlesearch').disabled = flag;
}
function searchFocus(e) {
// Update search input content on focus
if (e.value == 'Search') {
e.value = '';
e.className = '';
searchIsDisabled = false;
}
}
function searchBlur(e) {
// Update search input content on blur
if (e.value == '') {
e.value = 'Search';
e.className = 'disabled';
searchIsDisabled = true;
}
}
function actionsMenuInit(title) {
// Initialize action menu
for (i = 0; i < document.forms.length; i++) {
var form = document.forms[i];
if (form.className == 'actionsmenu') {
// Check if this form needs update
var div = form.getElementsByTagName('div')[0];
var label = div.getElementsByTagName('label')[0];
if (label) {
// This is the first time: remove label and do buton.
div.removeChild(label);
var dobutton = div.getElementsByTagName('input')[0];
div.removeChild(dobutton);
// and add menu title
var select = div.getElementsByTagName('select')[0];
var item = document.createElement('option');
item.appendChild(document.createTextNode(title));
item.value = 'show';
select.insertBefore(item, select.options[0]);
select.selectedIndex = 0;
}
}
}
}
//-->
</script>
<link rel="stylesheet" type="text/css" charset="utf-8" media="all" href="wiki/modern/css/common.css">
<link rel="stylesheet" type="text/css" charset="utf-8" media="screen" href="wiki/modern/css/screen.css">
<link rel="stylesheet" type="text/css" charset="utf-8" media="print" href="wiki/modern/css/print.css">
<link rel="stylesheet" type="text/css" charset="utf-8" media="projection" href="wiki/modern/css/projection.css">
<!-- css only for MSIE browsers -->
<!--[if IE]>
<link rel="stylesheet" type="text/css" charset="utf-8" media="all" href="wiki/modern/css/msie.css">
<![endif]-->
<link rel="Start" href="./Quake4SDK.html">
2021-04-10 13:40:18 +00:00
<link rel="Alternate" title="Wiki Markup" href="./Tutorial_ScriptEntities?action=raw">
<link rel="Alternate" media="print" title="Print View" href="./Tutorial_ScriptEntities?action=print">
<link rel="Search" href="./FindPage.html">
<link rel="Index" href="./TitleIndex.html">
<link rel="Glossary" href="./WordIndex.html">
<link rel="Help" href="./HelpOnFormatting.html">
</head>
<body lang="en" dir="ltr">
<div id="header">
<div id="logo"><a href="./Quake4SDK.html"><img src="wiki/common/moinmoin.png" alt="MoinMoin Logo"></a></div>
<form id="searchform" method="get" action="">
<div>
<input type="hidden" name="action" value="fullsearch">
<input type="hidden" name="context" value="180">
<label for="searchinput">Search:</label>
<input id="searchinput" type="text" name="value" value="" size="20"
onfocus="searchFocus(this)" onblur="searchBlur(this)"
onkeyup="searchChange(this)" onchange="searchChange(this)" alt="Search">
<input id="titlesearch" name="titlesearch" type="submit"
value="Titles" alt="Search Titles">
<input id="fullsearch" name="fullsearch" type="submit"
value="Text" alt="Search Full Text">
</div>
</form>
<script type="text/javascript">
<!--// Initialize search form
var f = document.getElementById('searchform');
f.getElementsByTagName('label')[0].style.display = 'none';
var e = document.getElementById('searchinput');
searchChange(e);
searchBlur(e);
//-->
</script>
2021-04-10 13:40:18 +00:00
<ul id="username"><li><a href="./Tutorial_ScriptEntities?action=login" id="login">Login</a></li></ul>
<div id="locationline">
<ul id="pagelocation">
2021-04-10 13:40:18 +00:00
<li><a class="backlink" title="Click to do a full-text search for this title" href="./Tutorial_ScriptEntities?action=fullsearch&amp;value=linkto%3A%22Tutorial+ScriptEntities%22&amp;context=180">Tutorial ScriptEntities</a></li>
</ul>
</div>
<ul id="navibar">
<li class="wikilink"><a href="./GettingStarted.html">GettingStarted</a></li><li class="wikilink"><a href="./ScriptFile.html">ScriptFile</a></li><li class="wikilink"><a href="./MakeAMod.html">MakeAMod</a></li><li class="wikilink"><a href="./LevelEditor.html">LevelEditor</a></li><li class="wikilink"><a href="./FXEditor.html">FXEditor</a></li><li class="wikilink"><a href="./GUIEditor.html">GUIEditor</a></li><li class="wikilink"><a href="./Sounds.html">Sounds</a></li><li class="wikilink"><a href="./Animations.html">Animations</a></li><li class="wikilink"><a href="./ArtReference.html">ArtReference</a></li><li class="wikilink"><a href="./DownloadableContent.html">DownloadableContent</a></li><li class="wikilink"><a href="./RecentChanges.html">RecentChanges</a></li><li class="wikilink"><a href="./FindPage.html">FindPage</a></li><li class="wikilink"><a href="./HelpContents.html">HelpContents</a></li><li class="current"><a href="./Tutorial_ScriptEntities.html">Tutorial ScriptEntities</a></li>
</ul>
<div id="pageline"><hr style="display:none;"></div>
2021-04-10 13:40:18 +00:00
<ul class="editbar"><li><span class="disabled">Immutable Page</span></li><li><a href="./Tutorial_ScriptEntities?action=info">Info</a></li><li><a href="./Tutorial_ScriptEntities?action=AttachFile">Attachments</a></li><li>
<form class="actionsmenu" method="get" action="">
<div>
<label>More Actions:</label>
<select name="action"
onchange="if ((this.selectedIndex != 0) &&
(this.options[this.selectedIndex].disabled == false)) {
this.form.submit();
}
this.selectedIndex = 0;">
<option value="raw">Raw Text</option>
<option value="print">Print View</option>
<option value="RenderAsDocbook">Render as Docbook</option>
<option value="refresh">Delete Cache</option>
<option value="show" disabled class="disabled">------------</option>
<option value="SpellCheck">Check Spelling</option>
<option value="LikePages">Like Pages</option>
<option value="LocalSiteMap">Local Site Map</option>
<option value="show" disabled class="disabled">------------</option>
<option value="RenamePage" disabled class="disabled">Rename Page</option>
<option value="DeletePage" disabled class="disabled">Delete Page</option>
<option value="show" disabled class="disabled">------------</option>
<option value="MyPages">My Pages</option>
<option value="SubscribeUser">Subscribe User</option>
<option value="show" disabled class="disabled">------------</option>
<option value="Despam">Remove Spam</option>
<option value="PackagePages">Package Pages</option>
</select>
<input type="submit" value="Do">
</div>
<script type="text/javascript">
<!--// Init menu
actionsMenuInit('More Actions:');
//-->
</script>
</form>
</li></ul>
</div>
<div id="page" lang="en" dir="ltr">
<div dir="ltr" id="content" lang="en"><span class="anchor" id="top"></span>
<span class="anchor" id="line-1"></span><p class="line867">
<h1 id="head-db2075940623837fbcd2b5203435ad2b4bdd76bc">The $ Symbol, Entities and You</h1>
<span class="anchor" id="line-2"></span><span class="anchor" id="line-3"></span><p class="line862">Any time you want to reference an entity in script, you need to use it's handle. Handles can be accessed directly, via the $ operator, or through <a href="./ScriptVariable.html#entity">entity variables</a>. Check out the examples <span class="anchor" id="line-4"></span><span class="anchor" id="line-5"></span><p class="line867">
<h2 id="head-cfd024b57ebb467f7c44e690da08f8d9d95092e8">Using $ to grab handles</h2>
<span class="anchor" id="line-6"></span><span class="anchor" id="line-7"></span><p class="line874">Use a dollar sign $ before the name of an entity to tell the scripting system that this is an entity. If you don’t use the $, the game won’t know what you’re talking about. <span class="anchor" id="line-8"></span><span class="anchor" id="line-9"></span><p class="line867"><span class="anchor" id="line-10"></span><span class="anchor" id="line-11"></span><span class="anchor" id="line-12"></span><span class="anchor" id="line-13"></span><span class="anchor" id="line-14"></span><span class="anchor" id="line-15"></span><div class="codearea" dir="ltr" lang="en">
<script type="text/javascript">
function isnumbered(obj) {
return obj.childNodes.length && obj.firstChild.childNodes.length && obj.firstChild.firstChild.className == 'LineNumber';
}
function nformat(num,chrs,add) {
var nlen = Math.max(0,chrs-(''+num).length), res = '';
while (nlen>0) { res += ' '; nlen-- }
return res+num+add;
}
function addnumber(did, nstart, nstep) {
var c = document.getElementById(did), l = c.firstChild, n = 1;
if (!isnumbered(c))
if (typeof nstart == 'undefined') nstart = 1;
if (typeof nstep == 'undefined') nstep = 1;
n = nstart;
while (l != null) {
if (l.tagName == 'SPAN') {
var s = document.createElement('SPAN');
s.className = 'LineNumber'
s.appendChild(document.createTextNode(nformat(n,4,' ')));
n += nstep;
if (l.childNodes.length)
l.insertBefore(s, l.firstChild)
else
l.appendChild(s)
}
l = l.nextSibling;
}
return false;
}
function remnumber(did) {
var c = document.getElementById(did), l = c.firstChild;
if (isnumbered(c))
while (l != null) {
if (l.tagName == 'SPAN' && l.firstChild.className == 'LineNumber') l.removeChild(l.firstChild);
l = l.nextSibling;
}
return false;
}
function togglenumber(did, nstart, nstep) {
var c = document.getElementById(did);
if (isnumbered(c)) {
remnumber(did);
} else {
addnumber(did,nstart,nstep);
}
return false;
}
</script>
<script type="text/javascript">
document.write('<a href="#" onclick="return togglenumber(\'CA-c105357339e94d12f9957ecb1a28f74bc1c9805c_000\', 1, 1);" \
class="codenumbers">Toggle line numbers<\/a>');
</script>
<pre dir="ltr" id="CA-c105357339e94d12f9957ecb1a28f74bc1c9805c_000" lang="en"><span class="line"><span class="LineNumber"> 1 </span></span>
<span class="line"><span class="LineNumber"> 2 </span> <span class="Comment">//open the door and show the monster</span></span>
<span class="line"><span class="LineNumber"> 3 </span> $<span class="ID">door_100</span><span class="SPChar">.</span><span class="ID">open</span><span class="SPChar">(</span><span class="SPChar">)</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 4 </span> $<span class="ID">monster_grunt_leftroom</span><span class="SPChar">.</span><span class="ID">show</span><span class="SPChar">(</span><span class="SPChar">)</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 5 </span></span>
</pre></div><span class="anchor" id="line-16"></span><span class="anchor" id="line-17"></span><p class="line867"><img alt="/!\" height="15" src="wiki/modern/img/alert.png" title="/!\" width="15" /> Again, If you're going to reference the objects by map name, you must use the $ operator. The following example won't work. <span class="anchor" id="line-18"></span><span class="anchor" id="line-19"></span><span class="anchor" id="line-20"></span><p class="line867"><span class="anchor" id="line-21"></span><span class="anchor" id="line-22"></span><span class="anchor" id="line-23"></span><span class="anchor" id="line-24"></span><span class="anchor" id="line-25"></span><div class="codearea" dir="ltr" lang="en">
<script type="text/javascript">
document.write('<a href="#" onclick="return togglenumber(\'CA-1cb1e46ca284a1a4a1b0b86bfebc264decd27ef5_001\', 1, 1);" \
class="codenumbers">Toggle line numbers<\/a>');
</script>
<pre dir="ltr" id="CA-1cb1e46ca284a1a4a1b0b86bfebc264decd27ef5_001" lang="en"><span class="line"><span class="LineNumber"> 1 </span></span>
<span class="line"><span class="LineNumber"> 2 </span> <span class="Comment">//this line will cause the script to not compile.</span></span>
<span class="line"><span class="LineNumber"> 3 </span> <span class="ID">door_100</span><span class="SPChar">.</span><span class="ID">open</span><span class="SPChar">(</span><span class="SPChar">)</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 4 </span></span>
</pre></div><span class="anchor" id="line-26"></span><span class="anchor" id="line-27"></span><p class="line862">If you reference something in script that isn't a <a href="./ScriptVariable.html">variable</a>, <a href="./ScriptSyntax.html">syntax</a>, or a map entity preceded by the $ operator, you'll get an <a href="./ScriptError_UnknownValueError.html">unknown value error</a>. <span class="anchor" id="line-28"></span><span class="anchor" id="line-29"></span><p class="line867">
<h2 id="head-59df83ade4b1e7519464a96632088bac78d5d877">Storing entity handles in variables</h2>
<span class="anchor" id="line-30"></span><span class="anchor" id="line-31"></span><p class="line862">Another way to reference entities in script is via the <a href="./ScriptVariable.html#entity">entity variable</a>. This allows you to write all purpose functions that get around hard coding. If you're familiar with C++, think of them as pointers. Otherwise, check out our example below. <span class="anchor" id="line-32"></span><span class="anchor" id="line-33"></span><p class="line867"><span class="anchor" id="line-34"></span><span class="anchor" id="line-35"></span><span class="anchor" id="line-36"></span><span class="anchor" id="line-37"></span><span class="anchor" id="line-38"></span><span class="anchor" id="line-39"></span><span class="anchor" id="line-40"></span><span class="anchor" id="line-41"></span><span class="anchor" id="line-42"></span><span class="anchor" id="line-43"></span><span class="anchor" id="line-44"></span><span class="anchor" id="line-45"></span><span class="anchor" id="line-46"></span><span class="anchor" id="line-47"></span><span class="anchor" id="line-48"></span><span class="anchor" id="line-49"></span><div class="codearea" dir="ltr" lang="en">
<script type="text/javascript">
document.write('<a href="#" onclick="return togglenumber(\'CA-146a8aad9c1e621d613570756a5149f555ce318d_002\', 1, 1);" \
class="codenumbers">Toggle line numbers<\/a>');
</script>
<pre dir="ltr" id="CA-146a8aad9c1e621d613570756a5149f555ce318d_002" lang="en"><span class="line"><span class="LineNumber"> 1 </span></span>
<span class="line"><span class="LineNumber"> 2 </span> <span class="ID">entity</span> <span class="ID">crazyDoor</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 3 </span></span>
<span class="line"><span class="LineNumber"> 4 </span> <span class="Comment">//Put the handle from door_100 into the crazyDoor variable.</span></span>
<span class="line"><span class="LineNumber"> 5 </span> <span class="ID">crazyDoor</span> <span class="SPChar">=</span> $<span class="ID">door_100</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 6 </span></span>
<span class="line"><span class="LineNumber"> 7 </span> <span class="Comment">//both of these calls affect the same entity!</span></span>
<span class="line"><span class="LineNumber"> 8 </span></span>
<span class="line"><span class="LineNumber"> 9 </span> <span class="Comment">//notice-- no $ sign</span></span>
<span class="line"><span class="LineNumber"> 10 </span> <span class="ID">crazyDoor</span><span class="SPChar">.</span><span class="ID">open</span><span class="SPChar">(</span><span class="SPChar">)</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 11 </span> <span class="ID">sys</span><span class="SPChar">.</span><span class="ID">wait</span><span class="SPChar">(</span><span class="Number">5</span><span class="SPChar">)</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 12 </span></span>
<span class="line"><span class="LineNumber"> 13 </span> <span class="Comment">//return of $</span></span>
<span class="line"><span class="LineNumber"> 14 </span> $<span class="ID">door_100</span><span class="SPChar">.</span><span class="ID">close</span><span class="SPChar">(</span><span class="SPChar">)</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 15 </span></span>
</pre></div><span class="anchor" id="line-50"></span><span class="anchor" id="line-51"></span><p class="line874">Why would we do this? Let imagine we want to create a function that opens a door and reveals a monster. Let's also say you're going to do this multiple times in your map, so instead of scripting it over and over again, you'll write a function for it. <span class="anchor" id="line-52"></span><span class="anchor" id="line-53"></span><p class="line867"><span class="anchor" id="line-54"></span><span class="anchor" id="line-55"></span><span class="anchor" id="line-56"></span><span class="anchor" id="line-57"></span><span class="anchor" id="line-58"></span><span class="anchor" id="line-59"></span><span class="anchor" id="line-60"></span><span class="anchor" id="line-61"></span><span class="anchor" id="line-62"></span><span class="anchor" id="line-63"></span><span class="anchor" id="line-64"></span><span class="anchor" id="line-65"></span><span class="anchor" id="line-66"></span><span class="anchor" id="line-67"></span><span class="anchor" id="line-68"></span><span class="anchor" id="line-69"></span><span class="anchor" id="line-70"></span><span class="anchor" id="line-71"></span><div class="codearea" dir="ltr" lang="en">
<script type="text/javascript">
document.write('<a href="#" onclick="return togglenumber(\'CA-05393096fe2679ac2f9614dbc21ae787a1b6b4fa_003\', 1, 1);" \
class="codenumbers">Toggle line numbers<\/a>');
</script>
<pre dir="ltr" id="CA-05393096fe2679ac2f9614dbc21ae787a1b6b4fa_003" lang="en"><span class="line"><span class="LineNumber"> 1 </span></span>
<span class="line"><span class="LineNumber"> 2 </span><span class="Comment">//this will open a door and reveal a monster!</span></span>
<span class="line"><span class="LineNumber"> 3 </span><span class="ResWord">void</span> <span class="ID">ohNoMonsterCloset</span><span class="SPChar">(</span> <span class="ID">entity</span> <span class="ID">theDoor</span><span class="SPChar">,</span> <span class="ID">entity</span> <span class="ID">theMonster</span> <span class="SPChar">)</span> <span class="SPChar">{</span></span>
<span class="line"><span class="LineNumber"> 4 </span> </span>
<span class="line"><span class="LineNumber"> 5 </span> <span class="ID">theDoor</span><span class="SPChar">.</span><span class="ID">open</span><span class="SPChar">(</span><span class="SPChar">)</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 6 </span> <span class="ID">theMonster</span><span class="SPChar">.</span><span class="ID">show</span><span class="SPChar">(</span><span class="SPChar">)</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 7 </span></span>
<span class="line"><span class="LineNumber"> 8 </span><span class="SPChar">}</span></span>
<span class="line"><span class="LineNumber"> 9 </span></span>
<span class="line"><span class="LineNumber"> 10 </span><span class="Comment">//now, in the rest of your script, you can toss this around:</span></span>
<span class="line"><span class="LineNumber"> 11 </span><span class="ResWord">void</span> <span class="ID">sendInTheBeasts</span><span class="SPChar">(</span><span class="SPChar">)</span> <span class="SPChar">{</span></span>
<span class="line"><span class="LineNumber"> 12 </span></span>
<span class="line"><span class="LineNumber"> 13 </span> <span class="ID">ohNoMonsterCloset</span><span class="SPChar">(</span> $<span class="ID">door1</span><span class="SPChar">,</span> $<span class="ID">monster_grunt_1</span><span class="SPChar">)</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 14 </span> <span class="ID">ohNoMonsterCloset</span><span class="SPChar">(</span> $<span class="ID">door_left</span><span class="SPChar">,</span> $<span class="ID">monster_gladiator_left</span> <span class="SPChar">)</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 15 </span> <span class="ID">ohNoMonsterCloset</span><span class="SPChar">(</span> $<span class="ID">backdoor</span><span class="SPChar">,</span> $<span class="ID">cheapmonster</span> <span class="SPChar">)</span><span class="SPChar">;</span></span>
<span class="line"><span class="LineNumber"> 16 </span></span>
<span class="line"><span class="LineNumber"> 17 </span><span class="SPChar">}</span></span>
</pre></div><span class="anchor" id="line-72"></span><span class="anchor" id="line-73"></span><p class="line867"><strong>Learn more about <a class="nonexistent" href="./Tutorial_WritingFunctions.html">writing your own functions</a>.</strong> <span class="anchor" id="line-74"></span><span class="anchor" id="bottom"></span></div><p id="pageinfo" class="info" lang="en" dir="ltr">Tutorial ScriptEntities (last edited 2005-11-02 20:36:21 by <span title="JimShepard @ 67.129.250.254[67.129.250.254]"><a class="nonexistent" href="./JimShepard.html" title="JimShepard @ 67.129.250.254[67.129.250.254]">JimShepard</a></span>)</p>
<div id="pagebottom"></div>
</div>
<div id="footer">
2021-04-10 13:40:18 +00:00
<ul class="editbar"><li><span class="disabled">Immutable Page</span></li><li><a href="./Tutorial_ScriptEntities?action=info">Info</a></li><li><a href="./Tutorial_ScriptEntities?action=AttachFile">Attachments</a></li><li>
<form class="actionsmenu" method="get" action="">
<div>
<label>More Actions:</label>
<select name="action"
onchange="if ((this.selectedIndex != 0) &&
(this.options[this.selectedIndex].disabled == false)) {
this.form.submit();
}
this.selectedIndex = 0;">
<option value="raw">Raw Text</option>
<option value="print">Print View</option>
<option value="RenderAsDocbook">Render as Docbook</option>
<option value="refresh">Delete Cache</option>
<option value="show" disabled class="disabled">------------</option>
<option value="SpellCheck">Check Spelling</option>
<option value="LikePages">Like Pages</option>
<option value="LocalSiteMap">Local Site Map</option>
<option value="show" disabled class="disabled">------------</option>
<option value="RenamePage" disabled class="disabled">Rename Page</option>
<option value="DeletePage" disabled class="disabled">Delete Page</option>
<option value="show" disabled class="disabled">------------</option>
<option value="MyPages">My Pages</option>
<option value="SubscribeUser">Subscribe User</option>
<option value="show" disabled class="disabled">------------</option>
<option value="Despam">Remove Spam</option>
<option value="PackagePages">Package Pages</option>
</select>
<input type="submit" value="Do">
</div>
<script type="text/javascript">
<!--// Init menu
actionsMenuInit('More Actions:');
//-->
</script>
</form>
</li></ul>
<ul id="credits">
<li><a href="http://moinmoin.wikiwikiweb.de/">MoinMoin Powered</a></li><li><a href="http://www.python.org/">Python Powered</a></li><li><a href="http://validator.w3.org/check?uri=referer">Valid HTML 4.01</a></li>
</ul>
</div>
</body>
</html>