gistfile1.txt

# An Introduction to Literate Programming, for "translators"

Start explaining how your Arras does *some area of technical expertise*, showing the code
behind what you're talking about as you explain. You must eventually use all
the code. Try to be logical in your explanation, for the sake of the human
reading it.  When you want to say that a particular chunk of code will be
defined and explained later and not show it now, use this syntax:

<<chunk name>>

Chunk name can be anything you want it to be. The names must be exact across
all references to the same chunk. (A "chunk" is a section of code with a label
that can be built up out across the explanation- we'll get to that soon.)

When you start explaining what a piece of code you promised you would explain
earlier would be, you should mention the code you're explaining:

<<chunk name>>=
code
@

To end a code chunk, just put an `@` symbol at the end. You can explain as much
code as you want in a single chunk.

You can also explain different chunks of code at the same time, or explain part
of a chunk and wait until later to explain the rest. Use the following syntax
to do this:

<<chunk name>>+
code
@

This syntax says "add to a chunk that already exists." When a chunk is
included, 
Using this same method, we can also interrupt a chunk to add to another. For
example:

<<initialize a new entity>>+
this.velocity = new Vector(0, 0);
@

We represent velocities as Vectors because vectors have both an X and a Y
component. Naturally, the X component is the horizontal speed of the entity
while the Y is the vertical speed. Together, Vectors also allow us to do some
cool things, like find the radial `direction` (angle) or total speed
(`length`). Total speed is the speed when factoring into account both X and Y
while ignoring the angle.

<<chunk name>>+
class Vector {
constructor(x, y) { //Vector constructor.
this.x = x;
this.y = y;
}

update() {
this.len = this.length;
this.dir = this.direction;
}

get length() {
return Math.sqrt(Math.pow(this.x, 2) + Math.pow(this.y, 2));
}
@

In addition, vectors have radial direction:
<<chunk name>>+
get direction() {
return Math.atan2(this.y, this.x);
}
}
@

To understand radial direction, imagine the X and the Y are plotted on a 2D
graph, the kind where there are two coordinate axes and four quadrants, and X
and Y can be negative. The direction tells you the [[I don't actually know what
that arctan2 means, will have to experiment to find out.]] 

Using the vector type makes sense when all of these properties (X, Y, length,
direction) are important. For example, with the AI controls target and goal,
goal is where the entity wants to move towards, and target is where the entity
wants to fire towards. But instead of being stored as an absolute X, Y
coordinate (i.e. relative to the entire arena), it's stored as X, Y coordinates
relative to the current entity's location. We'll have more on this later.

<<target and goal vectors>>+
target: new Vector(0, 0),
goal: new Vector(0, 0),
@

If you use the vector type in your own code, you'll want to 

There are other purposes for Vectors too. You should use a vector when there is
an X and a Y and it makes sense to look at the two numbers both in terms of the
DIRECTION and the SQRT(X^2, Y^2).

---
(example end)

[Small
Reminder.](https://gist.github.com/CrazyPython/d23fece19f6cd9b85698bcdb806e25c3)