Add an api function to retrieve unit skill experience.

Lua API.html

@@ -1109,6 +1109,12 @@ above operations accordingly. If enabled, pauses and zooms to position.</p>
 <li><p class="first"><tt class="docutils literal">dfhack.job.printItemDetails(jobitem,idx)</tt></p>
 <p>Prints info about the job item.</p>
 </li>
+<li><p class="first"><tt class="docutils literal">dfhack.job.getGeneralRef(job, type)</tt></p>
+<p>Searches for a general_ref with the given type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal">dfhack.job.getSpecificRef(job, type)</tt></p>
+<p>Searches for a specific_ref with the given type.</p>
+</li>
 <li><p class="first"><tt class="docutils literal">dfhack.job.getHolder(job)</tt></p>
 <p>Returns the building holding the job.</p>
 </li>
@@ -1147,6 +1153,12 @@ the flags in the job item.</p>
 <li><p class="first"><tt class="docutils literal">dfhack.units.getPosition(unit)</tt></p>
 <p>Returns true <em>x,y,z</em> of the unit, or <em>nil</em> if invalid; may be not equal to unit.pos if caged.</p>
 </li>
+<li><p class="first"><tt class="docutils literal">dfhack.units.getGeneralRef(unit, type)</tt></p>
+<p>Searches for a general_ref with the given type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal">dfhack.units.getSpecificRef(unit, type)</tt></p>
+<p>Searches for a specific_ref with the given type.</p>
+</li>
 <li><p class="first"><tt class="docutils literal">dfhack.units.getContainer(unit)</tt></p>
 <p>Returns the container (cage) item or <em>nil</em>.</p>
 </li>
@@ -1209,6 +1221,9 @@ is <em>true</em>, subtracts the rust penalty.</p>
 <li><p class="first"><tt class="docutils literal">dfhack.units.getEffectiveSkill(unit, skill)</tt></p>
 <p>Computes the effective rating for the given skill, taking into account exhaustion, pain etc.</p>
 </li>
+<li><p class="first"><tt class="docutils literal">dfhack.units.getExperience(unit, skill[, total])</tt></p>
+<p>Returns the experience value for the given skill. If <tt class="docutils literal">total</tt> is true, adds experience implied by the current rating.</p>
+</li>
 <li><p class="first"><tt class="docutils literal">dfhack.units.computeMovementSpeed(unit)</tt></p>
 <p>Computes number of frames * 100 it takes the unit to move in its current state of mind and body.</p>
 </li>
@@ -1403,6 +1418,12 @@ burrows, or the presence of invaders.</p>
 <div class="section" id="buildings-module">
 <h3><a class="toc-backref" href="#id25">Buildings module</a></h3>
 <ul>
+<li><p class="first"><tt class="docutils literal">dfhack.buildings.getGeneralRef(building, type)</tt></p>
+<p>Searches for a general_ref with the given type.</p>
+</li>
+<li><p class="first"><tt class="docutils literal">dfhack.buildings.getSpecificRef(building, type)</tt></p>
+<p>Searches for a specific_ref with the given type.</p>
+</li>
 <li><p class="first"><tt class="docutils literal">dfhack.buildings.setOwner(item,unit)</tt></p>
 <p>Replaces the owner of the building. If unit is <em>nil</em>, removes ownership.
 Returns <em>false</em> in case of error.</p>

Lua API.rst

@@ -970,6 +970,10 @@ Units module
 
   Computes the effective rating for the given skill, taking into account exhaustion, pain etc.
 
+* ``dfhack.units.getExperience(unit, skill[, total])``
+
+  Returns the experience value for the given skill. If ``total`` is true, adds experience implied by the current rating.
+
 * ``dfhack.units.computeMovementSpeed(unit)``
 
   Computes number of frames * 100 it takes the unit to move in its current state of mind and body.

library/LuaApi.cpp

@@ -1180,6 +1180,7 @@ static const LuaWrapper::FunctionReg dfhack_units_module[] = {
     WRAPM(Units, getAge),
     WRAPM(Units, getNominalSkill),
     WRAPM(Units, getEffectiveSkill),
+    WRAPM(Units, getExperience),
     WRAPM(Units, computeMovementSpeed),
     WRAPM(Units, getProfessionName),
     WRAPM(Units, getCasteProfessionName),

library/include/modules/Units.h

@@ -238,6 +238,8 @@ DFHACK_EXPORT double getAge(df::unit *unit, bool true_age = false);
 
 DFHACK_EXPORT int getNominalSkill(df::unit *unit, df::job_skill skill_id, bool use_rust = false);
 DFHACK_EXPORT int getEffectiveSkill(df::unit *unit, df::job_skill skill_id);
+DFHACK_EXPORT int getExperience(df::unit *unit, df::job_skill skill_id, bool total = false);
+
 DFHACK_EXPORT int computeMovementSpeed(df::unit *unit);
 
 struct NoblePosition {

library/modules/Units.cpp

@@ -909,6 +909,24 @@ int Units::getNominalSkill(df::unit *unit, df::job_skill skill_id, bool use_rust
     return 0;
 }
 
+int Units::getExperience(df::unit *unit, df::job_skill skill_id, bool total)
+{
+    CHECK_NULL_POINTER(unit);
+
+    if (!unit->status.current_soul)
+        return 0;
+
+    auto skill = binsearch_in_vector(unit->status.current_soul->skills, &df::unit_skill::id, skill_id);
+    if (!skill)
+        return 0;
+
+    int xp = skill->experience;
+    // exact formula used by the game:
+    if (total && skill->rating > 0)
+        xp += 500*skill->rating + 100*skill->rating*(skill->rating - 1)/2;
+    return xp;
+}
+
 int Units::getEffectiveSkill(df::unit *unit, df::job_skill skill_id)
 {
     /*