jps 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6b28b7b851c5c0a8c437e28c05b21d4a5bc808a7
+  data.tar.gz: d032f82ba7aa9b9c8759754a63ce7036f7a61fd0
+SHA512:
+  metadata.gz: 73b594670ef6bb4bb5030287e12e98e9366a8e7c0c5cd5b253d7a4f8ec57a7cba76201f3ab24a2c29156cad09d7a12684797eb9519e143c0170c9b48ed696b7d
+  data.tar.gz: 6a33cdcdcb403f3efd60b7dabaa06efe6d59c557af1aa3effd21bec29c3a43aa3064dd48248ec93fa14dd18d921641adb9555f834af10ae5f3aeabd024055484

data/ext/jps/extconf.rb

@@ -0,0 +1,3 @@
+require 'mkmf'
+$libs = '-lstdc++'
+create_makefile 'rjps'

data/ext/jps/jps.hh

@@ -0,0 +1,1539 @@
+#pragma once
+
+/*
+Public domain Jump Point Search implementation -- very fast pathfinding for uniform cost grids.
+Scroll down for compile config, usage tips, example code.
+
+License:
+  Public domain, WTFPL, CC0 or your favorite permissive license; whatever is available in your country.
+
+Dependencies:
+  libc (stdlib.h, math.h) by default, change defines below to use your own functions. (realloc(), free(), sqrt())
+  Compiles as C++98, does not require C++11 nor the STL.
+  Does not throw exceptions, works without RTTI, does not contain any virtual methods.
+
+Thread safety:
+  No global state. Searcher instances are not thread-safe. Grid template class is up to you.
+  If your grid access is read-only while pathfinding you may have many threads compute paths at the same time,
+  each with its own Searcher instance.
+
+Background:
+  If you want to generate paths on a map with the following properties:
+  - You have a 2D grid (exactly two dimensions!), where each tile has exactly 8 neighbors (up, down, left, right + diagonals)
+  - There is no "cost" -- a tile is either walkable, or not.
+  then you may want to avoid full fledged A* and go for Jump Point Search (this lib).
+  JPS is usually much faster than plain old A*, as long as your tile traversability check function is fast.
+
+Origin:
+  https://github.com/fgenesis/tinypile/blob/master/jps.hh
+
+Based on my older implementation:
+  https://github.com/fgenesis/jps/blob/master/JPS.h
+  (For changes compared to that version go to the end of this file)
+
+Inspired by:
+  http://users.cecs.anu.edu.au/~dharabor/data/papers/harabor-grastien-aaai11.pdf (The original paper)
+  https://github.com/Yonaba/Jumper
+  https://github.com/qiao/PathFinding.js
+
+Usage:
+
+  Define a class that overloads `operator()(x, y) const`, returning a value that can be treated as boolean.
+  You are responsible for bounds checking!
+  You want your operator() to be as fast and small as possible, as it will be called a LOT.
+  Ask your compiler to force-inline it if possible.
+
+// --- Begin example code ---
+
+struct MyGrid
+{
+    inline bool operator()(unsigned x, unsigned y) const // coordinates must be unsigned; method must be const
+    {
+        if(x < width && y < height) // Unsigned will wrap if < 0
+            ... return true if terrain at (x, y) is walkable.
+        // return false if terrain is not walkable or out-of-bounds.
+    }
+    unsigned width, height;
+};
+
+// Then you can retrieve a path:
+
+MyGrid grid(... set grid width, height, map data, whatever);
+
+const unsigned step = 0; // 0 compresses the path as much as possible and only records waypoints.
+                         // Set this to 1 if you want a detailed single-step path
+                         // (e.g. if you plan to further mangle the path yourself),
+                         // or any other higher value to output every Nth position.
+                         // (Waypoints are always output regardless of the step size.)
+
+JPS::PathVector path; // The resulting path will go here.
+                      // You may also use std::vector or whatever, as long as your vector type
+                      // has push_back(), begin(), end(), resize() methods (same semantics as std::vector).
+                      // Note that the path will NOT include the starting position!
+                      // --> If called with start == end it will report that a path has been found,
+                      //     but the resulting path vector will be empty!
+
+// Single-call interface:
+// (Further remarks about this function can be found near the bottom of this file.)
+// Note that the path vector is NOT cleared! New path points are appended at the end.
+bool found = JPS::findPath(path, grid, startx, starty, endx, endy, step);
+
+
+// --- Alternatively, if you want more control & efficiency for repeated pathfinding runs: ---
+
+// Use a Searcher instance (can be a class member, on the stack, ...)
+// Make sure the passed grid reference stays valid throughout the searcher's lifetime.
+// If you need control over memory allocation, you may pass an extra pointer that will be
+// forwarded to your own JPS_realloc & JPS_free if you've set those. Otherwise it's ignored.
+JPS::Searcher<MyGrid> search(grid, userPtr = NULL);
+
+// build path incrementally from waypoints:
+JPS::Position a, b, c, d = <...>; // set some waypoints
+if (search.findPath(path, a, b)
+ && search.findPath(path, b, c)
+ && search.findPath(path, c, d))
+{
+    // found path: a->b->c->d
+}
+
+// keep re-using existing pathfinder instance
+while(whatever)
+{
+    // Set startx, starty, endx, endy = <...>
+    if(!search.findPath(path, JPS::Pos(startx, starty), JPS::Pos(endx, endy), step))
+    {
+        // ...handle failure...
+    }
+}
+
+// If necessary, you may free internal memory -- this is never required; neither for performance, nor for correct function.
+// If you do pathfinding after freeing memory, it'll allocate new memory.
+// Note that freeing memory aborts any incremental search currently ongoing.
+search.freeMemory();
+
+// If you need to know how much memory is internally allocated by a searcher:
+unsigned bytes = search.getTotalMemoryInUse();
+
+
+// -------------------------------
+// --- Incremental pathfinding ---
+// -------------------------------
+
+Calling JPS::findPath() or Searcher<>::findPath() always computes an entire path or returns failure.
+If the path is long or costly and you have a tight CPU budget per frame you may want to perform pathfinding incrementally,
+stretched over multiple frames.
+
+First, call
+  ### JPS_Result res = search.findPathInit(Position start, Position end) ###
+Don't forget to check the return value, as it may return:
+- JPS_NO_PATH if one or both of the points are obstructed
+- JPS_EMPTY_PATH if the points are equal and not obstructed
+- JPS_FOUND_PATH if the initial greedy heuristic could find a path quickly.
+- JPS_OUT_OF_MEMORY if... well yeah.
+If it returns JPS_NEED_MORE_STEPS then the next part can start.
+
+Repeatedly call
+  ### JPS_Result res = search.findPathStep(int limit) ###
+until it returns JPS_NO_PATH or JPS_FOUND_PATH, or JPS_OUT_OF_MEMORY.
+For consistency, you will want to ensure that the grid does not change between subsequent calls;
+if the grid changes, parts of the path may go through a now obstructed area or may be no longer optimal.
+If limit is 0, it will perform the pathfinding in one go. Values > 0 pause the search
+as soon as possible after the number of steps was exceeded, returning NEED_MORE_STEPS.
+Use search.getStepsDone() after some test runs to find a good value for the limit.
+
+After getting JPS_FOUND_PATH, generate the actual path points via
+  ### JPS_Result res = search.findPathFinish(PathVector& path, unsigned step = 0) ###
+As described above, path points are appended, and granularity can be adjusted with the step parameter.
+Returns JPS_FOUND_PATH if the path was successfully built and appended to the path vector.
+Returns JPS_NO_PATH if the pathfinding did not finish or generating the path failed.
+May return JPS_OUT_OF_MEMORY if the path vector must be resized but fails to allocate.
+
+If findPathInit() or findPathStep() return JPS_OUT_OF_MEMORY, the current searcher progress becomes undefined.
+To recover, free some memory elsewhere and call findPathInit() to try again.
+
+If findPathFinish() returns out-of-memory but previous steps finished successfully,
+then the found path is still valid for generating the path vector.
+In that case you may call findPathFinish() again after making some memory available.
+
+If you do not worry about memory, treat JPS_OUT_OF_MEMORY as if JPS_NO_PATH was returned.
+
+You may pass JPS::PathVector, std::vector, or your own to findPathFinish().
+Note that if the path vector type you pass throws exceptions in case of allocation failures (std::vector does, for example),
+you'll get that exception, and the path vector will be in whatever state it was in when the last element was successfully inserted.
+If no exception is thrown (ie. you used JPS::PathVector) then the failure cases do not modify the path vector.
+
+You may abort a search anytime by starting a new one via findPathInit(), calling freeMemory(), or by destroying the searcher instance.
+Aborting or starting a search resets the values returned by .getStepsDone() and .getNodesExpanded() to 0.
+
+*/
+
+// ============================
+// ====== COMPILE CONFIG ======
+// ============================
+
+
+// If you want to avoid sqrt() or floats in general, define this.
+// Turns out in some testing this was ~12% faster, so it's the default.
+#define JPS_NO_FLOAT
+
+
+// ------------------------------------------------
+
+#include <stddef.h> // for size_t (needed for operator new)
+
+// Assertions
+#ifndef JPS_ASSERT
+# ifdef _DEBUG
+#  include <assert.h>
+#  define JPS_ASSERT(cond) assert(cond)
+# else
+#  define JPS_ASSERT(cond)
+# endif
+#endif
+
+// The default allocator uses realloc(), free(). Change if necessary.
+// You will get the user pointer that you passed to findPath() or the Searcher ctor.
+#if !defined(JPS_realloc) || !defined(JPS_free)
+# include <stdlib.h> // for realloc, free
+# ifndef JPS_realloc
+#  define JPS_realloc(p, newsize, oldsize, user) realloc(p, newsize)
+# endif
+# ifndef JPS_free
+#  define JPS_free(p, oldsize, user) free(p)
+# endif
+#endif
+
+#ifdef JPS_NO_FLOAT
+#define JPS_HEURISTIC_ACCURATE(a, b) (Heuristic::Chebyshev(a, b))
+#else
+# ifndef JPS_sqrt
+// for Euclidean heuristic.
+#  include <math.h>
+#  define JPS_sqrt(x) sqrtf(float(x)) // float cast here avoids a warning about implicit int->float cast
+# endif
+#endif
+
+// Which heuristics to use.
+// Basic property: Distance estimate, returns values >= 0. Smaller is better.
+// The accurate heuristic should always return guesses less or equal than the estimate heuristic,
+// otherwise the resulting paths may not be optimal.
+// (The rule of thumb is that the estimate is fast but can overestimate)
+// For the implementation of heuristics, scroll down.
+#ifndef JPS_HEURISTIC_ACCURATE
+#define JPS_HEURISTIC_ACCURATE(a, b) (Heuristic::Euclidean(a, b))
+#endif
+
+#ifndef JPS_HEURISTIC_ESTIMATE
+#define JPS_HEURISTIC_ESTIMATE(a, b) (Heuristic::Manhattan(a, b))
+#endif
+
+
+// --- Data types ---
+namespace JPS {
+
+// unsigned integer type wide enough to store a position on one grid axis.
+// Note that on x86, u32 is actually faster than u16.
+typedef unsigned PosType;
+
+// Result of heuristics. can also be (unsigned) int but using float by default since that's what sqrtf() returns
+// and we don't need to cast float->int that way. Change if you use integer-only heuristics.
+// (Euclidean heuristic using sqrt() works fine even if cast to int. Your choice really.)
+#ifdef JPS_NO_FLOAT
+typedef int ScoreType;
+#else
+typedef float ScoreType;
+#endif
+
+// Size type; used internally for vectors and the like. You can set this to size_t if you want, but 32 bits is more than enough.
+typedef unsigned SizeT;
+
+} // end namespace JPS
+
+
+// ================================
+// ====== COMPILE CONFIG END ======
+// ================================
+// ----------------------------------------------------------------------------------------
+
+typedef unsigned JPS_Flags;
+enum JPS_Flags_
+{
+    // No special behavior
+    JPS_Flag_Default       = 0x00,
+
+    // If this is defined, disable the greedy direct-short-path check that avoids the large area scanning that JPS does.
+    // This is just a performance tweak. May save a lot of CPU when constantly re-planning short paths without obstacles
+    // (e.g. an entity follows close behind another).
+    // Does not change optimality of results. If you perform your own line-of-sight checks
+    // before starting a pathfinding run you can disable greedy since checking twice isn't needed,
+    // but otherwise it's better to leave it enabled.
+    JPS_Flag_NoGreedy      = 0x01,
+
+    // If this is set, use standard A* instead of JPS (e.g. if you want to compare performance in your scenario).
+    // In most cases this will be MUCH slower, but might be beneficial if your grid lookup
+    // is slow (aka worse than O(1) or more than a few inlined instructions),
+    // as it avoids the large area scans that the JPS algorithm does.
+    // (Also increases memory usage as each checked position is expanded into a node.)
+    JPS_Flag_AStarOnly     = 0x02,
+
+    // Don't check whether start position is walkable.
+    // This makes the start position always walkable, even if the map data say otherwise.
+    JPS_Flag_NoStartCheck  = 0x04,
+
+    // Don't check whether end position is walkable.
+    JPS_Flag_NoEndCheck    = 0x08,
+};
+
+enum JPS_Result
+{
+    JPS_NO_PATH,
+    JPS_FOUND_PATH,
+    JPS_NEED_MORE_STEPS,
+    JPS_EMPTY_PATH,
+    JPS_OUT_OF_MEMORY
+};
+
+// operator new() without #include <new>
+// Unfortunately the standard mandates the use of size_t, so we need stddef.h the very least.
+// Trick via https://github.com/ocornut/imgui
+// "Defining a custom placement new() with a dummy parameter allows us to bypass including <new>
+// which on some platforms complains when user has disabled exceptions."
+struct JPS__NewDummy {};
+inline void* operator new(size_t, JPS__NewDummy, void* ptr) { return ptr; }
+inline void  operator delete(void*, JPS__NewDummy, void*)       {}
+#define JPS_PLACEMENT_NEW(p) new(JPS__NewDummy(), p)
+
+
+namespace JPS {
+
+struct Position
+{
+    PosType x, y;
+
+    inline bool operator==(const Position& p) const
+    {
+        return x == p.x && y == p.y;
+    }
+    inline bool operator!=(const Position& p) const
+    {
+        return x != p.x || y != p.y;
+    }
+
+    inline bool isValid() const { return x != PosType(-1); }
+};
+
+// The invalid position. Used internally to mark non-walkable points.
+static const Position npos = {PosType(-1), PosType(-1)};
+static const SizeT noidx = SizeT(-1);
+
+// ctor function to keep Position a real POD struct.
+inline static Position Pos(PosType x, PosType y)
+{
+    Position p;
+    p.x = x;
+    p.y = y;
+    return p;
+}
+
+template<typename T> inline static T Max(T a, T b) { return a < b ? b : a; }
+template<typename T> inline static T Min(T a, T b) { return a < b ? a : b; }
+template<typename T> inline static T Abs(T a)      { return a < T(0) ? -a : a; }
+template<typename T> inline static int Sgn(T val)  { return (T(0) < val) - (val < T(0)); }
+
+
+// Heuristics. Add new ones if you need them.
+namespace Heuristic
+{
+    inline ScoreType Manhattan(const Position& a, const Position& b)
+    {
+        const int dx = Abs(int(a.x - b.x));
+        const int dy = Abs(int(a.y - b.y));
+        return static_cast<ScoreType>(dx + dy);
+    }
+
+    inline ScoreType Chebyshev(const Position& a, const Position& b)
+    {
+        const int dx = Abs(int(a.x - b.x));
+        const int dy = Abs(int(a.y - b.y));
+        return static_cast<ScoreType>(Max(dx, dy));
+    }
+#ifdef JPS_sqrt
+    inline ScoreType Euclidean(const Position& a, const Position& b)
+    {
+        const int dx = (int(a.x - b.x));
+        const int dy = (int(a.y - b.y));
+        return static_cast<ScoreType>(JPS_sqrt(dx*dx + dy*dy));
+    }
+#endif
+} // end namespace heuristic
+
+
+
+// --- Begin infrastructure, data structures ---
+
+namespace Internal {
+
+// Never allocated outside of a PodVec<Node> --> All nodes are linearly adjacent in memory.
+struct Node
+{
+    ScoreType f, g; // heuristic distances
+    Position pos;
+    int parentOffs; // no parent if 0
+    unsigned _flags;
+
+    inline int hasParent() const { return parentOffs; }
+    inline void setOpen() { _flags |= 1; }
+    inline void setClosed() { _flags |= 2; }
+    inline unsigned isOpen() const { return _flags & 1; }
+    inline unsigned isClosed() const { return _flags & 2; }
+
+    // We know nodes are allocated sequentially in memory, so this is fine.
+    inline       Node& getParent()       { JPS_ASSERT(parentOffs); return this[parentOffs]; }
+    inline const Node& getParent() const { JPS_ASSERT(parentOffs); return this[parentOffs]; }
+    inline const Node *getParentOpt() const { return parentOffs ? this + parentOffs : 0; }
+    inline void setParent(const Node& p) { JPS_ASSERT(&p != this); parentOffs = static_cast<int>(&p - this); }
+};
+
+template<typename T>
+class PodVec
+{
+public:
+    PodVec(void *user = 0)
+        : _data(0), used(0), cap(0), _user(user)
+    {}
+    ~PodVec() { dealloc(); }
+    inline void clear()
+    {
+        used = 0;
+    }
+    void dealloc()
+    {
+        JPS_free(_data, cap * sizeof(T), _user);
+        _data = 0;
+        used = 0;
+        cap = 0;
+    }
+    T *alloc()
+    {
+        T *e = 0;
+        if(used < cap || _grow())
+        {
+            e = _data + used;
+            ++used;
+        }
+        return e;
+    }
+    inline void push_back(const T& e)
+    {
+        if(T *dst = alloc()) // yes, this silently fails when OOM. this is handled internally.
+            *dst = e;
+    }
+    inline void pop_back() { JPS_ASSERT(used); --used; }
+    inline T& back() { JPS_ASSERT(used); return _data[used-1]; }
+    inline SizeT size() const { return used; }
+    inline bool empty() const { return !used; }
+    inline T *data() { return _data; }
+    inline const T *data() const { return _data; }
+    inline T& operator[](size_t idx) const { JPS_ASSERT(idx < used); return _data[idx]; }
+    inline SizeT getindex(const T *e) const
+    {
+        JPS_ASSERT(e && _data <= e && e < _data + used);
+        return static_cast<SizeT>(e - _data);
+    }
+
+    void *_reserve(SizeT newcap) // for internal use
+    {
+        return cap < newcap ? _grow(newcap) : _data;
+    }
+    void resize(SizeT sz)
+    {
+        if(_reserve(sz))
+            used = sz;
+    }
+    SizeT _getMemSize() const
+    {
+        return cap * sizeof(T);
+    }
+
+    // minimal iterator interface
+    typedef T* iterator;
+    typedef const T* const_iterator;
+    typedef SizeT size_type;
+    typedef T value_type;
+    inline iterator begin() { return data(); }
+    inline iterator end() { return data() + size(); }
+    inline const_iterator cbegin() const { return data(); }
+    inline const_iterator cend() const { return data() + size(); }
+
+private:
+    void *_grow(SizeT newcap)
+    {
+        void *p = JPS_realloc(_data, newcap * sizeof(T), cap * sizeof(T), _user);
+        if(p)
+        {
+            _data = (T*)p;
+            cap = newcap;
+        }
+        return p;
+    }
+    void * _grow()
+    {
+        const SizeT newcap = cap + (cap / 2) + 32;
+        return _grow(newcap);
+    }
+    T *_data;
+    SizeT used, cap;
+
+public:
+    void * const _user;
+
+private:
+    // forbid ops
+    PodVec<T>& operator=(const PodVec<T>&);
+    PodVec(const PodVec<T>&);
+};
+
+template<typename T>
+inline static void Swap(T& a, T& b)
+{
+    const T tmp = a;
+    a = b;
+    b = tmp;
+}
+
+template<typename IT>
+inline static void Reverse(IT first, IT last)
+{
+    while((first != last) && (first != --last))
+    {
+        Swap(*first, *last);
+        ++first;
+    }
+}
+
+typedef PodVec<Node> Storage;
+
+
+class NodeMap
+{
+private:
+    static const unsigned LOAD_FACTOR = 8; // estimate: {CPU cache line size (64)} / sizeof(HashLoc)
+    static const unsigned INITIAL_BUCKETS = 16; // must be > 1 and power of 2
+
+    struct HashLoc
+    {
+        unsigned hash2; // for early-out check only
+        SizeT idx; // index in central storage
+    };
+    typedef PodVec<HashLoc> Bucket;
+
+    // hash function to determine bucket. only uses lower few bits. should jumble lower bits nicely.
+    static inline unsigned Hash(PosType x, PosType y)
+    {
+        return x ^ y;
+    }
+
+    // hash function designed to lose as little data as possible. for early-out checks. all bits used.
+    static inline unsigned Hash2(PosType x, PosType y)
+    {
+        return (y << 16) ^ x;
+    }
+
+public:
+
+    NodeMap(Storage& storage)
+        : _storageRef(storage), _buckets(storage._user)
+    {}
+
+    ~NodeMap()
+    {
+        dealloc();
+    }
+
+    void dealloc()
+    {
+        for(SizeT i = 0; i < _buckets.size(); ++i)
+            _buckets[i].~Bucket();
+        _buckets.dealloc();
+    }
+    void clear()
+    {
+        // clear the buckets, but *not* the bucket vector
+        for(SizeT i = 0; i <  _buckets.size(); ++i)
+            _buckets[i].clear();
+    }
+
+    Node *operator()(PosType x, PosType y)
+    {
+        const unsigned h = Hash(x, y);
+        const unsigned h2 = Hash2(x, y);
+        const SizeT ksz = _buckets.size(); // known to be power-of-2
+        Bucket *b = 0; // MSVC /W4 complains that this was uninitialized and used, so we init it...
+        if (ksz)
+        {
+            b = &_buckets[h & (ksz - 1)];
+            const SizeT bsz = b->size();
+            const HashLoc * const bdata = b->data();
+            for (SizeT i = 0; i < bsz; ++i)
+            {
+                // this is the only place where HashLoc::hash2 is used; it *could*be removed, which means:
+                // - twice as much space for indexes per cache line
+                // - but also higher chances for a cache miss because for each entry in the bucket we still need to check the node's X/Y coords,
+                //   and we'll likely end up in a random location in RAM for each node.
+                // Quick benchmarking showed that *with* the hash2 check it's almost immeasurably (less than 1%) faster.
+                if (bdata[i].hash2 == h2)
+                {
+                    Node &n = _storageRef[bdata[i].idx];
+                    if(n.pos.x == x && n.pos.y == y)
+                        return &n;
+                }
+            }
+        }
+
+        // enlarge hashmap if necessary; fix bucket if so
+        SizeT newbsz = _enlarge();
+        if(newbsz > 1)
+            b = &_buckets[h & (newbsz - 1)];
+        else if(newbsz == 1) // error case
+            return 0;
+
+        HashLoc *loc = b->alloc(); // ... see above. b is always initialized here. when ksz==0, _enlarge() will do its initial allocation, so it can never return 0.
+
+        if(!loc)
+            return 0;
+
+        loc->hash2 = h2;
+        loc->idx = _storageRef.size();
+
+        // no node at (x, y), create new one
+        Node *n = _storageRef.alloc();
+        if(n)
+        {
+            n->f = 0;
+            n->g = 0;
+            n->pos.x = x;
+            n->pos.y = y;
+            n->parentOffs = 0;
+            n->_flags = 0;
+        }
+        return n;
+    }
+
+    SizeT _getMemSize() const
+    {
+        SizeT sum = _buckets._getMemSize();
+        for(Buckets::const_iterator it = _buckets.cbegin(); it != _buckets.cend(); ++it)
+            sum += it->_getMemSize();
+        return sum;
+    }
+
+private:
+
+    // return values: 0 = nothing to do; 1 = error; >1: internal storage was enlarged to this many buckets
+    SizeT _enlarge()
+    {
+        const SizeT n = _storageRef.size();
+        const SizeT oldsz = _buckets.size();
+        if (n < oldsz * LOAD_FACTOR)
+            return 0;
+
+        // pre-allocate bucket storage that we're going to use
+        const SizeT newsz = oldsz ? oldsz * 2 : INITIAL_BUCKETS; // stays power of 2
+
+        if(!_buckets._reserve(newsz))
+            return 0; // early out if realloc fails; this not a problem and we can continue.
+
+        // forget everything
+        for(SizeT i = 0; i < oldsz; ++i)
+            _buckets[i].clear();
+
+        // resize and init
+        for(SizeT i = oldsz; i < newsz; ++i)
+        {
+            void *p = _buckets.alloc(); // can't fail since the space was reserved
+            JPS_PLACEMENT_NEW(p) PodVec<HashLoc>(_buckets._user);
+        }
+
+        const SizeT mask = _buckets.size() - 1;
+        for(SizeT i = 0; i < n; ++i)
+        {
+            const Position p = _storageRef[i].pos;
+            HashLoc *loc = _buckets[Hash(p.x, p.y) & mask].alloc();
+            if(!loc)
+                return 1; // error case
+
+            loc->hash2 = Hash2(p.x, p.y);
+            loc->idx = i;
+        }
+        return newsz;
+    }
+
+    Storage& _storageRef;
+    typedef PodVec<Bucket> Buckets;
+    Buckets _buckets;
+};
+
+class OpenList
+{
+private:
+    const Storage& _storageRef;
+    PodVec<SizeT> idxHeap;
+
+public:
+
+    OpenList(const Storage& storage)
+        : _storageRef(storage), idxHeap(storage._user)
+    {}
+
+
+    inline void pushNode(Node *n)
+    {
+        _heapPushIdx(_storageRef.getindex(n));
+    }
+
+    inline Node& popNode()
+    {
+        return _storageRef[_popIdx()];
+    }
+
+    // re-heapify after node changed its order
+    inline void fixNode(const Node& n)
+    {
+        const unsigned ni = _storageRef.getindex(&n);
+        const unsigned sz = idxHeap.size();
+        unsigned *p = idxHeap.data();
+        for(unsigned i = 0; i < sz; ++i) // TODO: if this ever becomes a perf bottleneck: make it so that each node knows its heap index
+            if(p[i] == ni)
+            {
+                _fixIdx(i);
+                return;
+            }
+            JPS_ASSERT(false); // expect node to be found
+    }
+
+    inline void dealloc() { idxHeap.dealloc(); }
+    inline void clear()   { idxHeap.clear(); }
+    inline bool empty() const { return idxHeap.empty(); }
+
+    inline SizeT _getMemSize() const
+    {
+        return idxHeap._getMemSize();
+    }
+
+private:
+
+    inline bool _heapLess(SizeT a, SizeT b)
+    {
+        return _storageRef[idxHeap[a]].f > _storageRef[idxHeap[b]].f;
+    }
+
+    inline bool _heapLessIdx(SizeT a, SizeT idx)
+    {
+        return _storageRef[idxHeap[a]].f > _storageRef[idx].f;
+    }
+
+    void _percolateUp(SizeT i)
+    {
+        const SizeT idx = idxHeap[i];
+        SizeT p;
+        goto start;
+        do
+        {
+            idxHeap[i] = idxHeap[p]; // parent is smaller, move it down
+            i = p;                   // continue with parent
+start:
+            p = (i - 1) >> 1;
+        }
+        while(i && _heapLessIdx(p, idx));
+        idxHeap[i] = idx; // found correct place for idx
+    }
+
+    void _percolateDown(SizeT i)
+    {
+        const SizeT idx = idxHeap[i];
+        const SizeT sz = idxHeap.size();
+        SizeT child;
+        goto start;
+        do
+        {
+            // pick right sibling if exists and larger or equal
+            if(child + 1 < sz && !_heapLess(child+1, child))
+                ++child;
+            idxHeap[i] = idxHeap[child];
+            i = child;
+start:
+            child = (i << 1) + 1;
+        }
+        while(child < sz);
+        idxHeap[i] = idx;
+        _percolateUp(i);
+    }
+
+    void _heapPushIdx(SizeT idx)
+    {
+        SizeT i = idxHeap.size();
+        idxHeap.push_back(idx);
+        _percolateUp(i);
+    }
+
+    SizeT _popIdx()
+    {
+        SizeT sz = idxHeap.size();
+        JPS_ASSERT(sz);
+        const SizeT root = idxHeap[0];
+        idxHeap[0] = idxHeap[--sz];
+        idxHeap.pop_back();
+        if(sz > 1)
+            _percolateDown(0);
+        return root;
+    }
+
+    // re-heapify node at index i
+    inline void _fixIdx(SizeT i)
+    {
+        _percolateDown(i);
+        _percolateUp(i);
+    }
+};
+
+#undef JPS_PLACEMENT_NEW
+
+// --- End infrastructure, data structures ---
+
+// All those things that don't depend on template parameters...
+class SearcherBase
+{
+protected:
+    Storage storage;
+    OpenList open;
+    NodeMap nodemap;
+
+    Position endPos;
+    SizeT endNodeIdx;
+    JPS_Flags flags;
+    int stepsRemain;
+    SizeT stepsDone;
+
+
+    SearcherBase(void *user)
+        : storage(user)
+        , open(storage)
+        , nodemap(storage)
+        , endPos(npos), endNodeIdx(noidx)
+        , flags(0)
+        , stepsRemain(0), stepsDone(0)
+    {}
+
+    void clear()
+    {
+        open.clear();
+        nodemap.clear();
+        storage.clear();
+        endNodeIdx = noidx;
+        stepsDone = 0;
+    }
+
+    void _expandNode(const Position jp, Node& jn, const Node& parent)
+    {
+        JPS_ASSERT(jn.pos == jp);
+        ScoreType extraG = JPS_HEURISTIC_ACCURATE(jp, parent.pos);
+        ScoreType newG = parent.g + extraG;
+        if(!jn.isOpen() || newG < jn.g)
+        {
+            jn.g = newG;
+            jn.f = jn.g + JPS_HEURISTIC_ESTIMATE(jp, endPos);
+            jn.setParent(parent);
+            if(!jn.isOpen())
+            {
+                open.pushNode(&jn);
+                jn.setOpen();
+            }
+            else
+                open.fixNode(jn);
+        }
+    }
+
+public:
+
+    template <typename PV>
+    JPS_Result generatePath(PV& path, unsigned step) const;
+
+    void freeMemory()
+    {
+        open.dealloc();
+        nodemap.dealloc();
+        storage.dealloc();
+        endNodeIdx = noidx;
+    }
+
+    // --- Statistics ---
+
+    inline SizeT getStepsDone() const { return stepsDone; }
+    inline SizeT getNodesExpanded() const { return storage.size(); }
+
+    SizeT getTotalMemoryInUse() const
+    {
+        return storage._getMemSize()
+             + nodemap._getMemSize()
+             + open._getMemSize();
+    }
+};
+
+template <typename GRID> class Searcher : public SearcherBase
+{
+public:
+    Searcher(const GRID& g, void *user = 0)
+        : SearcherBase(user), grid(g)
+    {}
+
+    // single-call
+    template<typename PV>
+    bool findPath(PV& path, Position start, Position end, unsigned step, JPS_Flags flags = JPS_Flag_Default);
+
+    // incremental pathfinding
+    JPS_Result findPathInit(Position start, Position end, JPS_Flags flags = JPS_Flag_Default);
+    JPS_Result findPathStep(int limit);
+    // generate path after one was found
+    template<typename PV>
+    JPS_Result findPathFinish(PV& path, unsigned step) const;
+
+private:
+
+    const GRID& grid;
+
+    Node *getNode(const Position& pos);
+    bool identifySuccessors(const Node& n);
+
+    bool findPathGreedy(Node *start, Node *end);
+    
+    unsigned findNeighborsAStar(const Node& n, Position *wptr);
+
+    unsigned findNeighborsJPS(const Node& n, Position *wptr) const;
+    Position jumpP(const Position& p, const Position& src);
+    Position jumpD(Position p, int dx, int dy);
+    Position jumpX(Position p, int dx);
+    Position jumpY(Position p, int dy);
+
+    // forbid any ops
+    Searcher& operator=(const Searcher<GRID>&);
+    Searcher(const Searcher<GRID>&);
+};
+
+
+// -----------------------------------------------------------------------
+
+template<typename PV> JPS_Result SearcherBase::generatePath(PV& path, unsigned step) const
+{
+    if(endNodeIdx == noidx)
+        return JPS_NO_PATH;
+    const SizeT offset = path.size();
+    SizeT added = 0;
+    const Node& endNode = storage[endNodeIdx];
+    const Node *next = &endNode;
+    if(!next->hasParent())
+        return JPS_NO_PATH;
+    if(step)
+    {
+        const Node *prev = endNode.getParentOpt();
+        if(!prev)
+            return JPS_NO_PATH;
+        do
+        {
+            const unsigned x = next->pos.x, y = next->pos.y;
+            int dx = int(prev->pos.x - x);
+            int dy = int(prev->pos.y - y);
+            const int adx = Abs(dx);
+            const int ady = Abs(dy);
+            JPS_ASSERT(!dx || !dy || adx == ady); // known to be straight, if diagonal
+            const int steps = Max(adx, ady);
+            dx = int(step) * Sgn(dx);
+            dy = int(step) * Sgn(dy);
+            int dxa = 0, dya = 0;
+            for(int i = 0; i < steps; i += step)
+            {
+                path.push_back(Pos(x+dxa, y+dya));
+                ++added;
+                dxa += dx;
+                dya += dy;
+            }
+            next = prev;
+            prev = prev->getParentOpt();
+        }
+        while (prev);
+    }
+    else
+    {
+        do
+        {
+            JPS_ASSERT(next != &next->getParent());
+            path.push_back(next->pos);
+            ++added;
+            next = &next->getParent();
+        }
+        while (next->hasParent());
+    }
+
+    // JPS::PathVector silently discards push_back() when memory allocation fails;
+    // detect that case and roll back.
+    if(path.size() != offset + added)
+    {
+        path.resize(offset);
+        return JPS_OUT_OF_MEMORY;
+    }
+
+    // Nodes were traversed backwards, fix that
+    Reverse(path.begin() + offset, path.end());
+    return JPS_FOUND_PATH;
+}
+
+//-----------------------------------------
+
+template <typename GRID> inline Node *Searcher<GRID>::getNode(const Position& pos)
+{
+    JPS_ASSERT(grid(pos.x, pos.y));
+    return nodemap(pos.x, pos.y);
+}
+
+template <typename GRID> Position Searcher<GRID>::jumpP(const Position &p, const Position& src)
+{
+    JPS_ASSERT(grid(p.x, p.y));
+
+    int dx = int(p.x - src.x);
+    int dy = int(p.y - src.y);
+    JPS_ASSERT(dx || dy);
+
+    if(dx && dy)
+        return jumpD(p, dx, dy);
+    else if(dx)
+        return jumpX(p, dx);
+    else if(dy)
+        return jumpY(p, dy);
+
+    // not reached
+    JPS_ASSERT(false);
+    return npos;
+}
+
+template <typename GRID> Position Searcher<GRID>::jumpD(Position p, int dx, int dy)
+{
+    JPS_ASSERT(grid(p.x, p.y));
+    JPS_ASSERT(dx && dy);
+
+    const Position endpos = endPos;
+    unsigned steps = 0;
+
+    while(true)
+    {
+        if(p == endpos)
+            break;
+
+        ++steps;
+        const PosType x = p.x;
+        const PosType y = p.y;
+
+        if( (grid(x-dx, y+dy) && !grid(x-dx, y)) || (grid(x+dx, y-dy) && !grid(x, y-dy)) )
+            break;
+
+        const bool gdx = !!grid(x+dx, y);
+        const bool gdy = !!grid(x, y+dy);
+
+        if(gdx && jumpX(Pos(x+dx, y), dx).isValid())
+            break;
+
+        if(gdy && jumpY(Pos(x, y+dy), dy).isValid())
+            break;
+
+        if((gdx || gdy) && grid(x+dx, y+dy))
+        {
+            p.x += dx;
+            p.y += dy;
+        }
+        else
+        {
+            p = npos;
+            break;
+        }
+    }
+    stepsDone += steps;
+    stepsRemain -= steps;
+    return p;
+}
+
+template <typename GRID> inline Position Searcher<GRID>::jumpX(Position p, int dx)
+{
+    JPS_ASSERT(dx);
+    JPS_ASSERT(grid(p.x, p.y));
+
+    const PosType y = p.y;
+    const Position endpos = endPos;
+    unsigned steps = 0;
+
+    unsigned a = ~((!!grid(p.x, y+1)) | ((!!grid(p.x, y-1)) << 1));
+
+    while(true)
+    {
+        const unsigned xx = p.x + dx;
+        const unsigned b = (!!grid(xx, y+1)) | ((!!grid(xx, y-1)) << 1);
+
+        if((b & a) || p == endpos)
+            break;
+        if(!grid(xx, y))
+        {
+            p = npos;
+            break;
+        }
+
+        p.x += dx;
+        a = ~b;
+        ++steps;
+    }
+
+    stepsDone += steps;
+    stepsRemain -= steps;
+    return p;
+}
+
+template <typename GRID> inline Position Searcher<GRID>::jumpY(Position p, int dy)
+{
+    JPS_ASSERT(dy);
+    JPS_ASSERT(grid(p.x, p.y));
+
+    const PosType x = p.x;
+    const Position endpos = endPos;
+    unsigned steps = 0;
+
+    unsigned a = ~((!!grid(x+1, p.y)) | ((!!grid(x-1, p.y)) << 1));
+
+    while(true)
+    {
+        const unsigned yy = p.y + dy;
+        const unsigned b = (!!grid(x+1, yy)) | ((!!grid(x-1, yy)) << 1);
+
+        if((a & b) || p == endpos)
+            break;
+        if(!grid(x, yy))
+        {
+            p = npos;
+            break;
+        }
+
+        p.y += dy;
+        a = ~b;
+        ++steps;
+    }
+
+    stepsDone += steps;
+    stepsRemain -= steps;
+    return p;
+}
+
+#define JPS_CHECKGRID(dx, dy) (grid(x+(dx), y+(dy)))
+#define JPS_ADDPOS(dx, dy)     do { *w++ = Pos(x+(dx), y+(dy)); } while(0)
+#define JPS_ADDPOS_CHECK(dx, dy) do { if(JPS_CHECKGRID(dx, dy)) JPS_ADDPOS(dx, dy); } while(0)
+#define JPS_ADDPOS_NO_TUNNEL(dx, dy) do { if(grid(x+(dx),y) || grid(x,y+(dy))) JPS_ADDPOS_CHECK(dx, dy); } while(0)
+
+template <typename GRID> unsigned Searcher<GRID>::findNeighborsJPS(const Node& n, Position *wptr) const
+{
+    Position *w = wptr;
+    const unsigned x = n.pos.x;
+    const unsigned y = n.pos.y;
+
+    if(!n.hasParent())
+    {
+        // straight moves
+        JPS_ADDPOS_CHECK(-1, 0);
+        JPS_ADDPOS_CHECK(0, -1);
+        JPS_ADDPOS_CHECK(0, 1);
+        JPS_ADDPOS_CHECK(1, 0);
+
+        // diagonal moves + prevent tunneling
+        JPS_ADDPOS_NO_TUNNEL(-1, -1);
+        JPS_ADDPOS_NO_TUNNEL(-1, 1);
+        JPS_ADDPOS_NO_TUNNEL(1, -1);
+        JPS_ADDPOS_NO_TUNNEL(1, 1);
+
+        return unsigned(w - wptr);
+    }
+    const Node& p = n.getParent();
+    // jump directions (both -1, 0, or 1)
+    const int dx = Sgn<int>(x - p.pos.x);
+    const int dy = Sgn<int>(y - p.pos.y);
+
+    if(dx && dy)
+    {
+        // diagonal
+        // natural neighbors
+        const bool walkX = !!grid(x+dx, y);
+        if(walkX)
+            *w++ = Pos(x+dx, y);
+        const bool walkY = !!grid(x, y+dy);
+        if(walkY)
+            *w++ = Pos(x, y+dy);
+
+        if(walkX || walkY)
+            JPS_ADDPOS_CHECK(dx, dy);
+
+        // forced neighbors
+        if(walkY && !JPS_CHECKGRID(-dx,0))
+            JPS_ADDPOS_CHECK(-dx, dy);
+
+        if(walkX && !JPS_CHECKGRID(0,-dy))
+            JPS_ADDPOS_CHECK(dx, -dy);
+    }
+    else if(dx)
+    {
+        // along X axis
+        if(JPS_CHECKGRID(dx, 0))
+        {
+            JPS_ADDPOS(dx, 0);
+
+             // Forced neighbors (+ prevent tunneling)
+            if(!JPS_CHECKGRID(0, 1))
+                JPS_ADDPOS_CHECK(dx, 1);
+            if(!JPS_CHECKGRID(0,-1))
+                JPS_ADDPOS_CHECK(dx,-1);
+        }
+    }
+    else if(dy)
+    {
+        // along Y axis
+        if(JPS_CHECKGRID(0, dy))
+        {
+            JPS_ADDPOS(0, dy);
+
+            // Forced neighbors (+ prevent tunneling)
+            if(!JPS_CHECKGRID(1, 0))
+                JPS_ADDPOS_CHECK(1, dy);
+            if(!JPS_CHECKGRID(-1, 0))
+                JPS_ADDPOS_CHECK(-1,dy);
+        }
+    }
+
+    return unsigned(w - wptr);
+}
+
+//-------------- Plain old A* search ----------------
+template <typename GRID> unsigned Searcher<GRID>::findNeighborsAStar(const Node& n, Position *wptr)
+{
+    Position *w = wptr;
+    const int x = n.pos.x;
+    const int y = n.pos.y;
+    const int d = 1;
+    JPS_ADDPOS_NO_TUNNEL(-d, -d);
+    JPS_ADDPOS_CHECK    ( 0, -d);
+    JPS_ADDPOS_NO_TUNNEL(+d, -d);
+    JPS_ADDPOS_CHECK    (-d,  0);
+    JPS_ADDPOS_CHECK    (+d,  0);
+    JPS_ADDPOS_NO_TUNNEL(-d, +d);
+    JPS_ADDPOS_CHECK    ( 0, +d);
+    JPS_ADDPOS_NO_TUNNEL(+d, +d);
+    stepsDone += 8;
+    return unsigned(w - wptr);
+}
+
+//-------------------------------------------------
+#undef JPS_ADDPOS
+#undef JPS_ADDPOS_CHECK
+#undef JPS_ADDPOS_NO_TUNNEL
+#undef JPS_CHECKGRID
+
+
+template <typename GRID> bool Searcher<GRID>::identifySuccessors(const Node& n_)
+{
+    const SizeT nidx = storage.getindex(&n_);
+    const Position np = n_.pos;
+    Position buf[8];
+
+    const int num = (flags & JPS_Flag_AStarOnly)
+        ? findNeighborsAStar(n_, &buf[0])
+        : findNeighborsJPS(n_, &buf[0]);
+
+    for(int i = num-1; i >= 0; --i)
+    {
+        // Invariant: A node is only a valid neighbor if the corresponding grid position is walkable (asserted in jumpP)
+        Position jp;
+        if(flags & JPS_Flag_AStarOnly)
+            jp = buf[i];
+        else
+        {
+            jp = jumpP(buf[i], np);
+            if(!jp.isValid())
+                continue;
+        }
+        // Now that the grid position is definitely a valid jump point, we have to create the actual node.
+        Node *jn = getNode(jp); // this might realloc the storage
+        if(!jn)
+            return false; // out of memory
+
+        Node& n = storage[nidx]; // get valid ref in case we realloc'd
+        JPS_ASSERT(jn != &n);
+        if(!jn->isClosed())
+            _expandNode(jp, *jn, n);
+    }
+    return true;
+}
+
+template <typename GRID> template<typename PV> bool Searcher<GRID>::findPath(PV& path, Position start, Position end, unsigned step, JPS_Flags flags)
+{
+    JPS_Result res = findPathInit(start, end, flags);
+
+    // If this is true, the resulting path is empty (findPathFinish() would fail, so this needs to be checked before)
+    if(res == JPS_EMPTY_PATH)
+        return true;
+
+    while(true)
+    {
+        switch(res)
+        {
+            case JPS_NEED_MORE_STEPS:
+                res = findPathStep(0);
+                break; // the switch
+
+            case JPS_FOUND_PATH:
+                return findPathFinish(path, step) == JPS_FOUND_PATH;
+
+            case JPS_EMPTY_PATH:
+                JPS_ASSERT(false); // can't happen
+                // fall through
+            case JPS_NO_PATH:
+            case JPS_OUT_OF_MEMORY:
+                return false;
+        }
+    }
+}
+
+template <typename GRID> JPS_Result Searcher<GRID>::findPathInit(Position start, Position end, JPS_Flags flags)
+{
+    // This just resets a few counters; container memory isn't touched
+    this->clear();
+
+    this->flags = flags;
+    endPos = end;
+
+    // FIXME: check this
+    if(start == end && !(flags & (JPS_Flag_NoStartCheck|JPS_Flag_NoEndCheck)))
+    {
+        // There is only a path if this single position is walkable.
+        // But since the starting position is omitted in the output, there is nothing to do here.
+        return grid(end.x, end.y) ? JPS_EMPTY_PATH : JPS_NO_PATH;
+    }
+
+    if(!(flags & JPS_Flag_NoStartCheck))
+        if(!grid(start.x, start.y))
+            return JPS_NO_PATH;
+
+    if(!(flags & JPS_Flag_NoEndCheck))
+        if(!grid(end.x, end.y))
+            return JPS_NO_PATH;
+
+    Node *endNode = getNode(end); // this might realloc the internal storage...
+    if(!endNode)
+        return JPS_OUT_OF_MEMORY;
+    endNodeIdx = storage.getindex(endNode); // .. so we keep this for later
+
+    Node *startNode = getNode(start); // this might also realloc
+    if(!startNode)
+        return JPS_OUT_OF_MEMORY;
+    endNode = &storage[endNodeIdx]; // startNode is valid, make sure that endNode is valid too in case we reallocated
+
+    if(!(flags & JPS_Flag_NoGreedy))
+    {
+        // Try the quick way out first
+        if(findPathGreedy(startNode, endNode))
+            return JPS_FOUND_PATH;
+    }
+
+    open.pushNode(startNode);
+
+    return JPS_NEED_MORE_STEPS;
+}
+
+template <typename GRID> JPS_Result Searcher<GRID>::findPathStep(int limit)
+{
+    stepsRemain = limit;
+    do
+    {
+        if(open.empty())
+            return JPS_NO_PATH;
+        Node& n = open.popNode();
+        n.setClosed();
+        if(n.pos == endPos)
+            return JPS_FOUND_PATH;
+        if(!identifySuccessors(n))
+            return JPS_OUT_OF_MEMORY;
+    }
+    while(stepsRemain >= 0);
+    return JPS_NEED_MORE_STEPS;
+}
+
+template<typename GRID> template<typename PV> JPS_Result Searcher<GRID>::findPathFinish(PV& path, unsigned step) const
+{
+    return this->generatePath(path, step);
+}
+
+template<typename GRID> bool Searcher<GRID>::findPathGreedy(Node *n, Node *endnode)
+{
+    Position midpos = npos;
+    PosType x = n->pos.x;
+    PosType y = n->pos.y;
+    const Position endpos = endnode->pos;
+
+    JPS_ASSERT(x != endpos.x || y != endpos.y); // must not be called when start==end
+    JPS_ASSERT(n != endnode);
+
+    int dx = int(endpos.x - x);
+    int dy = int(endpos.y - y);
+    const int adx = Abs(dx);
+    const int ady = Abs(dy);
+    dx = Sgn(dx);
+    dy = Sgn(dy);
+
+    // go diagonally first
+    if(x != endpos.x && y != endpos.y)
+    {
+        JPS_ASSERT(dx && dy);
+        const int minlen = Min(adx, ady);
+        const PosType tx = x + dx * minlen;
+        while(x != tx)
+        {
+            if(grid(x, y) && (grid(x+dx, y) || grid(x, y+dy))) // prevent tunneling as well
+            {
+                x += dx;
+                y += dy;
+            }
+            else
+                return false;
+        }
+
+        if(!grid(x, y))
+            return false;
+
+        midpos = Pos(x, y);
+    }
+
+    // at this point, we're aligned to at least one axis
+    JPS_ASSERT(x == endpos.x || y == endpos.y);
+
+    if(!(x == endpos.x && y == endpos.y))
+    {
+        while(x != endpos.x)
+            if(!grid(x += dx, y))
+                return false;
+
+        while(y != endpos.y)
+            if(!grid(x, y += dy))
+                return false;
+
+        JPS_ASSERT(x == endpos.x && y == endpos.y);
+    }
+
+    if(midpos.isValid())
+    {
+        const unsigned nidx = storage.getindex(n);
+        Node *mid = getNode(midpos); // this might invalidate n, endnode
+        if(!mid)
+            return false;
+        n = &storage[nidx]; // reload pointers
+        endnode = &storage[endNodeIdx];
+        JPS_ASSERT(mid && mid != n);
+        mid->setParent(*n);
+        if(mid != endnode)
+            endnode->setParent(*mid);
+    }
+    else
+        endnode->setParent(*n);
+
+    return true;
+}
+
+#undef JPS_ASSERT
+#undef JPS_realloc
+#undef JPS_free
+#undef JPS_sqrt
+#undef JPS_HEURISTIC_ACCURATE
+#undef JPS_HEURISTIC_ESTIMATE
+
+
+} // end namespace Internal
+
+using Internal::Searcher;
+
+typedef Internal::PodVec<Position> PathVector;
+
+// Single-call convenience function. For efficiency, do NOT use this if you need to compute paths repeatedly.
+//
+// Returns: 0 if failed or no path could be found, otherwise number of steps taken.
+//
+// path: If the function returns success, the path is appended to this vector.
+//       The path does NOT contain the starting position, i.e. if start and end are the same,
+//       the resulting path has no elements.
+//       The vector does not have to be empty. The function does not clear it;
+//       instead, the new path positions are appended at the end.
+//       This allows building a path incrementally.
+//
+// grid: Functor, expected to overload operator()(x, y), return true if position is walkable, false if not.
+//
+// step: If 0, only return waypoints.
+//       If 1, create exhaustive step-by-step path.
+//       If N, put in one position for N blocks travelled, or when a waypoint is hit.
+//       All returned points are guaranteed to be on a straight line (vertically, horizontally, or diagonally),
+//       and there is no obstruction between any two consecutive points.
+//       Note that this parameter does NOT influence the pathfinding in any way;
+//       it only controls the coarseness of the output path.
+template <typename GRID, typename PV>
+SizeT findPath(PV& path, const GRID& grid, PosType startx, PosType starty, PosType endx, PosType endy,
+               unsigned step = 0, // optional
+               JPS_Flags flags = JPS_Flag_Default,
+               void *user = 0)    // memory allocation userdata
+{
+    Searcher<GRID> search(grid, user);
+    if(!search.findPath(path, Pos(startx, starty), Pos(endx, endy), step, flags))
+        return 0;
+    const SizeT done = search.getStepsDone();
+    return done + !done; // report at least 1 step; as 0 would indicate failure
+}
+
+} // end namespace JPS
+
+
+/*
+Changes compared to the older JPS.h at https://github.com/fgenesis/jps:
+
+- Explicitly freeing memory is no longer necessary. The freeMemory() method is still there
+  and does its thing (drop all internal storage), but you never have to call it explicitly.
+  Unlike the old version, there will be no performance degradation if you don't free memory every now and then.
+  Actually it'll be slightly slower if you free memory and pathfind again for the first time,
+  as it has to re-allocate internal data structures.
+
+- Searcher::getNodesExpanded() is now reset to 0 upon starting a search.
+
+- Added optional JPS_Flags parameter to pathfind (-init) functions to control search
+  behavior. Compile-time #defines are gone.
+
+- Removed skip parameter. Imho that one just added confusion and no real benefit.
+  If you want it back for some reason: poke me, open an issue, whatever.
+
+- Renamed JPS::Result to JPS_Result. Enum values gained JPS_ prefix, so JPS::NO_PATH is now JPS_NO_PATH, and so on.
+
+- Added one more JPS_Result value: JPS_OUT_OF_MEMORY. See info block at the top how to handle this.
+
+- Changed signature of Searcher<>::findPathFinish() to return JPS_Result (was bool).
+  This is more in line with the other 2 methods, as it can now return JPS_OUT_OF_MEMORY.
+
+- Changed signature of JPS::findPath(). Nonzero return is still success. Pointers to output stats are gone.
+  Use a Searcher instance if you need the details.
+
+- This version no longer depends on the C++ STL: <algorithm>, <vector>, <map>, operator new(), all gone.
+  Makes things more memory- and cache-friendly, and quite a bit faster, too.
+
+- The canonical file name is now "jps.hh" instead of "JPS.h"
+*/
+
+
+/*
+TODO:
+- make int -> DirType
+- make possible to call findPathStep()/findPathFinish() even when JPS_EMPTY_PATH was returned on init (simplifies switch-case)
+- make node know its heap index
+- optional diagonals (make runtime param)
+*/