https://jensarps.github.io/cockpit.js/

1<!DOCTYPE html>
2<html>
3<head>
4    <meta charset='utf-8'>
5
6    <title>cockpit.js</title>
7    <link rel="stylesheet" href="/css/style.css" />
8    

8<script type="text/javascript">
9
10        var _gaq = _gaq || [];
11        _gaq.push(['_setAccount', 'UA-10931011-2']);
12        _gaq.push(['_trackPageview']);
13
14        (function() {
15            var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
16            ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
17            var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
18        })();
19
20    </script>

20
21</head>
22
23<body>
24<a href="https://github.com/jensarps/cockpit.js"><img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" /></a>
25
26<div id="container">
27
28    <h1><a href="https://github.com/jensarps/cockpit.js">cockpit.js</a></h1>
29
30    <div class="description">
31        A retro-style 2D cockpit overlay for your 3D game
32    </div>
33
34    <p>cockpit.js lets you add an retro-style 2D cockpit overlay to your 3D game and
35        lets you move it around, vibrate and shake it to simulate the player's head
36        movement and/or physical impact on the ship/car/plane/vehicle.</p>
37
38    <p>The idea is strikingly simple and has worked for years in simulators (and is
39        still being used today in games). I figured that the implementation would be
40        strikingly simple as well and gave it a shot on a sunday night. But, I like it,
41        and plan to add more features to it without increasing it's low complexity.</p>
42
43    <h1>Usage</h1>
44
45    <p>Grab the cockpit.js file and include it in your page via script tag or pull it
46        in using an AMD loader like require.js.</p>
47
48    <p>To add a cockpit to your game, just create a new Cockpit instance and pass the
49        path to the cockpit overlay image:</p>
50
51    <p><code>var cockpit = new Cockpit('path/to/my/overlay.png');</code></p>
52
53    <h2>Basic Effects</h2>
54
55    <p>The most basic thing to do now is to move your cockpit around:</p>
56
57    <p><code>cockpit.move(horizontalValue, verticalValue);</code></p>
58
59    <p>The two values you have to pass must be numbers ranging from 0 to 1, where 1 is  the maximum movement.</p>
60
61    <p>Next, make your cockpit vibrate for a set duration:</p>
62
63    <p><code>cockpit.vibrate(duration);</code></p>
64
65    <p>Duration is passed in ms and optional, defaulting to 600ms.</p>
66
67    <p>

67If you don't now upfront how long your cockpit is going to vibrate, use the following two methods:</p>
68
69    <p><code>cockpit.beginVibrate();</code> and <code>cockpit.endVibrate();</code></p>
70
71    <p>If things go hairy, e.g. your vehicle is being hit, you can shake your cockpit:</p>
72
73    <p><code>cockpit.shake(intensity, duration);</code></p>
74
75    <p>Where intensity is a number from 0 to 1. Duration is passed in ms. Both arguments are optional, intensity defaulting to 0.5 and duration to 300.</p>
76
77    <p>As with vibrating, you can shake the cockpit for an unknown amount of time using</p>
78
79    <p><code>cockpit.beginShake(intensity);</code> and <code>cockpit.endShake();</code></p>
80
81    <p>The intensity param is optional and works as described above.</p>
82
83    <p>Instead of the begin/end methods, you can also use the following method:</p>
84
85    <p><code>cockpit.setState(state);</code></p>
86
87    <p>where state is one of 'normal', 'vibrate' or 'shake'. You can't pass any options for now (it will use default values), but you have a convenient method to toggle between the different states.</p>
88
89    <h2>Text Items</h2>
90
91    <p>You can also add some HUD-like text items to your cockpit, that will move around with the cockpit:</p>
92
93    <p><code>cockpit.addText(id, textToDisplay);</code></p>
94
95    <p>The id is applied to the text item's DOMNode, so you can use it to position and style it. For positioning, I recommend to use absolute positioning with percentages so that the text will stay in place independent of window size (well, almost, soo TODO section).</p>
96
97    <p>To update your text item, just call</p>
98
99    <p><code>cockpit.updateText(id, textToDisplay);</code></p>
100
101    <p>with the id you previously passed and the new text.</p>
102
103    <h2>Custom Timer / Render Loop</h2>
104
105    <p>By default, cockpit.js uses <code>window</code>'s timeout and interval methods. If you want to move all DOM modifications caused by moving/vibrating/shaking into a render loop (and you will probably want to), you can pass a custom timer to the constructor:</p>
106
107    <p><code>var cockpit = new Cockpit('path/to/my/overlay.png', myTimer);</code></p>
108
109    <p>That timer needs to provide the <code>setTimeout</code>, <code>setInterval</code> and <code>clearInterval</code> methods. </p>
110
111    <p>Why using a render loop and custom timer? A quick example: If your cockpit is in a vibrating state, and the player pauses the game, your cockpit would continue shaking, even though the game is paused. </p>
112
113    <p>But, code is better than words, see example #3 and view-source.</p>
114
115    <p>

115A pausable timer can be found <a href="https://github.com/jensarps/game-timer">here</a> (this is the one I use in the example).</p>
116
117    <h1>Demos</h1>
118
119    <ul>
120        <li><a href="http://jensarps.github.com/cockpit.js/demo/three">Using cockpit.js over a three.js example.</a> When you get too close to the earth's atmosphere, the ship will start to vibrate and lose speed. Observe the HUD to see your current thrust, speed and g-force.</li>
121        <li><a href="http://jensarps.github.com/cockpit.js/demo/plain">A cockpit over a white background.</a> Yeah. Just for a quick test. Doubleclick to shake, right click to vibrate.</li>
122        <li><a href="http://jensarps.github.com/cockpit.js/demo/custom-timer">cockpit.js using a custom timer and a render loop.</a> Double click to start vibrating, and pause/unpause the render loop.</li>
123    </ul>
124
125
126    <h2>Author</h2>
127    <p><a href="https://github.com/jensarps">Jens Arps</a></p>
128
129    <h2>Contact</h2>
130    <p>Ping me on Twitter: <a href="https://twitter.com/#!/jensarps">@jensarps</a></p>
131
132    <div class="footer">
133        get the source code on GitHub : <a href="https://github.com/je

133nsarps/cockpit.js">jensarps/cockpit.js</a>
134    </div>
135
136</div>
137</body>
138</html>