On this page

# Turtle

Class Turtle instances represent the dynamic, behavioral element of modeling. Each turtle knows the patch it is on, and interacts with that and other patches, as well as other turtles. Turtles are also the end points of Links.

You do not call `new Turtle()`, instead class Turtles creates Turtle instances via Turtles#create or Turtles#createOne

I.e. class Turtles is a factory for all of it's Turtle instances. So don't do this:

## Constructor

### new Turtle()

Source
  - Turtle.js, line 16

## Members

### (readonly) dx

A property for the x-increment if the turtle were to take one step forward in its current heading.

Source
  - Turtle.js, line 365

### (readonly) dy

A property for the y-increment if the turtle were to take one step forward in its current heading.

Source
  - Turtle.js, line 373

### heading

Return this Turtle's heading

Source
  - Turtle.js, line 110

### heading

Sets this Turtle's heading

Source
  - Turtle.js, line 116

### links

Returns an array of the Links that have this Turtle as one of the end points

Source
  - Turtle.js, line 92

### patch

Return the patch this Turtle is on. Return null if Turtle off-world.

Source
  - Turtle.js, line 103

## Methods

### canMove(distance) → {Boolean}

Can I move forward by distance and not be off-world?

Parameters:

Name | Type | Description
--- | --- | ---
`distance` | number | The distance ahead

Source
  - Turtle.js, line 329

Returns:

True if moving forward by distance is on-world

Type:
  Boolean

### die()

Ask this turtle to "die"

- Removes itself from the Turtles array
- Removes itself from any Turtles breeds
- Removes all my Links if any exist
- Removes me from my Patch list of turtles on it
- Set it's id to -1 to indicate to others it's gone

Source
  - Turtle.js, line 40

### distance(agent) → {number}

Return distance from me to the Patch or Turtle

2.5D: use z too if both agent.z and this.z exist

Parameters:

Name | Type | Description
--- | --- | ---
`agent` | Patch | Turtle |

Source
  - Turtle.js, line 356

Returns:

distance in patch coordinates.

Type:
  number

### distanceXY(x, y, zopt) → {number}

Distance from this turtle to x, y No off-world test done.

2.5D: use z too if both z & this.z exist.

Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`x` | number |  |  |
`y` | number |  |  |
`z` | number | undefined | <optional> | null |

Source
  - Turtle.js, line 343

Returns:

distance in patch coordinates.

Type:
  number

### face(agent)

Turn turtle so at to be facing the given Turtle or Patch

Parameters:

Name | Type | Description
--- | --- | ---
`agent` | Patch | Turtle | The agent to face towards

Source
  - Turtle.js, line 278

### facexy(x, y)

Turn turtle so at to be facing the given x, y patch coordinate

Parameters:

Name | Type | Description
--- | --- | ---
`x` | number | The x coordinate
`y` | number | The y coordinate

Source
  - Turtle.js, line 288

### forward(d)

Move forward, along the Turtle's heading d units in Patch coordinates

Parameters:

Name | Type | Description
--- | --- | ---
`d` | number | The distance to move

Source
  - Turtle.js, line 240

### handleEdge(x, y, zopt)

Handle turtle x,y,z if turtle off-world. Uses the Turtle's atEdge property to determine how to manage the Turtle. Defaults to 'wrap', wrapping the x,y,z to the opposite edge.

atEdge can be:

- 'die'
- 'wrap'
- 'bounce'
- 'clamp'
- 'random'
- a function called with the Turtle as it's argument

Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`x` | number |  | Turtle's x coord
`y` | number |  | Turtle's y coord
`z` | number | undefined | <optional> | Turtle's z coord if not undefined

Source
  - Turtle.js, line 186

### hatch(numopt, breedopt, initopt) → {Array}

Factory method: create num new turtles at this turtle's location.

Parameters:

Name | Type | Attributes | Default | Description
--- | --- | --- | --- | ---
`num` | number | <optional> | 1 | The number of new turtles to create
`breed` | AgentSet | <optional> | this.agentSet | The type of turtles to create, defaults to my type
`init` | function | <optional> | turtle => {} | A function to initialize the new turtles, defaults to no-op

Source
  - Turtle.js, line 74

Returns:

An Array of the new Turtles, generally ignored due to the init function

Type:
  Array

### isLinkNeighbor(t) → {Boolean}

Is the given Turtle linked to me?

Parameters:

Name | Type | Description
--- | --- | ---
`t` | Turtle |

Source
  - Turtle.js, line 448

Returns:

Type:
  Boolean

### left(angle)

Turn Turtle left by angle

Parameters:

Name | Type | Description
--- | --- | ---
`angle` | number | The angle to rotate by

Source
  - Turtle.js, line 269

### linkNeighbors() → {Array}

Return all turtles linked to me. Basically me.otherEnd of all my links.

Source
  - Turtle.js, line 440

Returns:

All the turtles linked to me

Type:
  Array

### moveTo(agent)

Place the turtle at the given patch/turtle location

Parameters:

Name | Type | Description
--- | --- | ---
`agent` | Patch | Turtle | A Patch or Turtle who's location is used

Source
  - Turtle.js, line 231

### otherEnd(l) → {Turtle}

Return the other end of this link from me. Link must include me!

See links property for all my links, if any.

Parameters:

Name | Type | Description
--- | --- | ---
`l` | Link |

Source
  - Turtle.js, line 432

Returns:

The other turtle making this Link

Type:
  Turtle

### patchAhead(distance) → {Patch|undefined}

Return the patch ahead of this turtle by distance. Return undefined if the distance puts the patch off-world

Parameters:

Name | Type | Description
--- | --- | ---
`distance` | number | The distance ahead

Source
  - Turtle.js, line 299

Returns:

The patch at the distance ahead of this Turtle

Type:
  Patch | undefined

### patchAt(dx, dy) → {Patch|undefined}

The patch at dx, dy from my current position. Return undefined if off-world

Parameters:

Name | Type | Description
--- | --- | ---
`dx` | number | The delta x ahead
`dy` | number | The delta y ahead

Source
  - Turtle.js, line 404

Returns:

The patch dx, dy ahead; undefined if off-world

Type:
  Patch | undefined

### patchAtHeadingAndDistance(heading, distance) → {Patch|undefined}

Return the patch at the absolute, not relative heading and distance from this turtle. Return undefined if off-world

Use the Left/Right versions for relative heading.

Parameters:

Name | Type | Description
--- | --- | ---
`heading` | number | The absolute angle from this turtle
`distance` | number | The distance ahead

Source
  - Turtle.js, line 417

Returns:

The Patch, or undefined if off-world

Type:
  Patch | undefined

### patchLeftAndAhead(angle, distance) → {Patch|undefined}

Return the patch angle to the left and ahead by distance Return undefined if the distance puts the patch off-world

Parameters:

Name | Type | Description
--- | --- | ---
`angle` | number | The angle to the left
`distance` | number | The distance ahead

Source
  - Turtle.js, line 321

Returns:

The patch found, or undefined if off-world

Type:
  Patch | undefined

### patchRightAndAhead(angle, distance) → {Patch|undefined}

Return the patch angle to the right and ahead by distance Return undefined if the distance puts the patch off-world

Parameters:

Name | Type | Description
--- | --- | ---
`angle` | number | The angle to the right
`distance` | number | The distance ahead

Source
  - Turtle.js, line 309

Returns:

The patch found, or undefined if off-world

Type:
  Patch | undefined

### right(angle)

Turn Turtle right by angle

Parameters:

Name | Type | Description
--- | --- | ---
`angle` | number | The angle to rotate by

Source
  - Turtle.js, line 261

### rotate(angle)

Change Turtle's heading by angle

Parameters:

Name | Type | Description
--- | --- | ---
`angle` | number | The angle to rotate by

Source
  - Turtle.js, line 252

### setxy(x, y, zopt)

Set Turtles x, y position. If z given, override default z of 0.

Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`x` | number |  | Turtle's x coord, a Float in patch space
`y` | number |  | Turtle's Y coord, a Float in patch space
`z` | number | undefined | <optional> | Turtle's Z coord if given

Source
  - Turtle.js, line 142

### subtractHeading(heading) → {Angle}

Computes the difference between the my heading and the given heading, the smallest angle by which t could be rotated to produce heading.

Parameters:

Name | Type | Description
--- | --- | ---
`heading` | Angle | The heading I wish to be roated to.

Source
  - Turtle.js, line 126

Returns:

Type:
  Angle

### towards(agent) → {number}

Return the heading towards the Patch or Turtle given.

Parameters:

Name | Type | Description
--- | --- | ---
`agent` | Patch | Turtle | The agent who's angle from this Turtle we use

Source
  - Turtle.js, line 382

Returns:

The angle towards the agent

Type:
  number

### towardsXY(x, y) → {number}

Return the heading towards the given x,y coordinates.

Parameters:

Name | Type | Description
--- | --- | ---
`x` | number | The x coordinarte
`y` | number | The y coordinarte

Source
  - Turtle.js, line 391

Returns:

The angle towards x,y

Type:
  number

Type anything to view search result