iddevnet/quake4/Tutorial_ScriptEntities.html
2021-04-10 17:07:40 +02:00

358 lines
24 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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">
<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>
<ul id="username"><li><a href="./Tutorial_ScriptEntities?action=login" id="login">Login</a></li></ul>
<div id="locationline">
<ul id="pagelocation">
<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>
<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">
<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>