Jump to content
Sign in to follow this  
You need to play a total of 5 battles to post in this section.
MatroseFuchs

[ModAPI] Documentation

13 comments in this topic

Recommended Posts

Administrator
10 posts
17 battles

PythonAPI - Battle

Working with "battle" methods is only possible after entering a battle (for a situation when an event is triggered, see the "events" methods), otherwise methods do not return anything as information they handle is only available in battle. To handle events you need to use "events.onSFMEvent" (see the description below in the "events" methods), returned parameters of this event are "eventName" (an event name), "eventData" (a dict with event parameters).

Available methods:

battle

  • getPlayersInfo()
  • getPlayerInfo(playerId)
  • getSelfPlayerInfo()
  • getPlayerInfoByName(name)
  • getPlayerShipInfo(playerId)
  • getPlayerByVehicleId(shipID)
  • getAmmoParams(ammoID)
  • isVehicleBurning(shipID)
  • isVehicleFlooding(shipID)
  • isBattleStarted() 

battle.getPlayersInfo()

This function returns a dict, where keys are "playerID", and values are dict "PlayerInfo" with various information about the player.

To view the result, you can pass it to the "World_of_Warships\profile\python.log" file via "print", or write it in a separate file "open('filename', 'w')".

battle_getPlayersInfo_en.pngbattle_getPlayersInfo_log.png


battle.getPlayerInfo(playerId)

This function returns an object with player information.

The input parameter is playerId (the player’s ID). The returned value is PlayerInfo.


battle.getSelfPlayerInfo()

This function returns an object with information about the player. The returned value is PlayerInfo.


battle.getPlayerInfoByName(name)

This function returns an object with information about the player.

The input parameter is name (the player’s nickname). The returned value is PlayerInfo.


battle.getPlayerShipInfo(playerId)

This function returns an object with information about the player’s ship.

The input parameter is playerId (the player’s ID). The returned value is ShipInfo.


battle.getPlayerByVehicleId(shipID)

This function returns an object with information about the player.

The input parameter is shipId (the ship’s ID). The returned value is PlayerInfo.


battle.getAmmoParams(ammoID)

This function returns an object with information about the shell.

The input parameter is ammoId (the shell ID, this value can be obtained in the event handler function "events.onReceiveShellInfo(func)" (see the description in the "events" methods).


battle.isVehicleBurning(shipID)

This function returns True if the ship is on fire, or False if it isn’t; for example, you can use it in the event handler function "events.onReceiveShellInfo(func)" (see the description in the "events" methods).

The input parameter is ID (the ship ID).


battle.isVehicleFlooding(shipID)

This function returns True if a shell hitting the ship caused flooding, or False if it’s not the case; it is recommended to use it in the same way as "isVehicleBurning".

The input parameter is ID (the ship ID).


battle.isBattleStarted() 

This function returns True if the battle has started.

Share this post


Link to post
Share on other sites
Administrator
10 posts
17 battles

PythonAPI - Callbacks

"Callbacks" methods are designed for calling functions multiple times.

Available methods:

callbacks

  • callbacks.perTick(func)
  • callbacks.callback(dt, func, *args, **kw)
  • callbacks.cancel(handle)

callbacks.perTick(func)

This function calls a user function passed as a parameter every tick (several times per second!)*.

The input parameter is the user function "func" that will be called by this method every tick.

The returned value is “handle”, it’s a unique method identifier used to stop a call for a function by a tick.

callbacks_perTick_en.png

 

*Warning!!!

Be careful when using this method, it can bring to poor performance of the game client.

 


callbacks.callback(dt, func, *args, **kw)

This function also takes the user function "func" as a parameter that will be called each time (repeatedly, again and again) with a set delay (an interval in seconds).

Input parameters:

  • delaytime – a delay in seconds indicating when the func function will be called
  • func – a function to be called
  • *args – positional arguments that will be passed to the func function
  • **kwargs – named arguments that will be passed to the func function

The returned value is handle, it’s a unique identifier used to stop a call for a function by tick.

callbacks_callback.png


callbacks.cancel(handle)

This function finishes operation of the method that called the function every tick or at a set interval.

The input parameter is a unique identifier of the handle method called by the functions perTick and callback.

Share this post


Link to post
Share on other sites
Administrator
10 posts
17 battles

PythonAPI - CustomPorts

"CustomPorts" methods allow you to add your own port.

Available methods:

customPorts

  • customPorts.addCustomPort(portName, portDisplayName = DEFAULT_NAME, isPremium = False, peculiarities = None)
  • customPorts.removeCustomPort(portName)

customPorts.addCustomPort(portName, portDisplayName = DEFAULT_NAME, isPremium = False, peculiarities = None)

This method adds a new port to the port selection menu.

Function parameters:

  • portName - a name, a port identifier, it must coincide with the space and port png-icon name
  • portDisplayName = 'Personal' – a displayed port name
  • isPremium = False - if the port is premium or not
  • peculiarities = None - an array of the port’s peculiarities (e.g. "peculiarities = [ 'arpeggio' ]")

customPorts.removeCustomPort(portName)

This method removed the new port from the port selection menu.

The input parameter is portName; it’s a name, an identifier of the uploaded port.

Share this post


Link to post
Share on other sites
Administrator
10 posts
17 battles

PythonAPI - Events

"Events" methods allow you to work with different events in the game client (opening a window, pressing a button in the menu, pressing a keyboard button, going to battle, etc.).

Available methods:

events

  • events.onFlashReady(func)
  • events.onSFMEvent(func)
  • events.onReceiveShellInfo(func)
  • events.onBattleStarted(func)
  • events.onBattleQuit(func)
  • events.onKeyEvent(func)
  • events.onMouseEvent(func)
  • events.onGotRibbon(func)
  • events.onAchievementEarned(func)

Events are called from the outside and pass various parameters and functions subscribed to these events. An example of subscription to an event: events.eventName(myEventHandlerFunc).


events.onFlashReady(func)

This event is triggered immediately after a Flash part of the "Main.swf" mod is loaded and initialized (if available).

The input parameter is func, it’s a handler function for the event (def func(modName): ), it gets modName as an input argument, it’s a name of the mod containing the loaded Flash part.


events.onSFMEvent(func)

This method allows you to work with various SFM machine events, such as showing or hiding different windows, pressing some buttons, pressing a keyboard or mouse button, entering a battle, etc.

The input parameter is "func", it is a handler function for events that takes two parameters from the SFM machine, such as eventName (an event name), and eventData (dict with event parameters).

events_onSFMEvent.png


events.onReceiveShellInfo(func)

This event is triggered when damage is dealt/received to the enemy/from the enemy by shells/torpedoes.

The event handler function "func(*args, **kwargs)" handling the event receives the following parameters:

  • victimID - shipID an identifier of the attacked ship
  • shooterID - shipID an identifier of the attacking ship
  • ammoID - a shell type
  • matID - a type of material that was hit
  • shootID - ID, a shot identifier
  • booleans - a type of damage after taking a hit (this value has a bit mask):
  1. our ship was damaged
  2. armor penetration
  3. damage under water
  4. the ship is destroyed
  5. a shell went through the ship
  6. a ricochet off the armor
  7. splash damage
  8. main caliber guns are destroyed
  9. torpedo launchers are destroyed
  10. secondary battery is destroyed
  • damage - the amount of dealt damage
  • shotPosition - a tuple with coordinates of the point of impact
  • yaw - yaw of the shell, its angle of impact
  • hlinfo - a tuple with the information about the salvo (list with damage info, salvo ID or salvo number)

events_onReceiveShellInfo.png


events.onBattleStarted(func)

This event is triggered when a battle starts, after the timer countdown finishes before the battle.


events.onBattleQuit(func)

This event is triggered when exiting a battle and/or exiting the game.
It takes the handler function "func" as an argument: when handling an event, the function gets one argument - "True".


events.onKeyEvent(func)

This method is triggered when keyboard or mouse buttons are pressed after entering the game (when the port is loaded).
It takes the event handler function "func" as an argument, the function gets the event object with different info about pressed keyboard/mouse buttons.

E.g.: def func(event), where "event" is the event object with the following properties:

  • event.key - a code of the pressed keyboard key (import Keys – grants access to keyboard constants: Keys.KEY_F1 is "F1" key, Keys.KEY_Q is Q key, etc.)
  • event.isKeyDown() - the function checks if any key is pressed and returns "True" or "False"
  • event.isKeyUp() - the function checks if the key was unpressed after being pressed and returns "True" or "False"
  • event.isShiftDown() - checks if "Shift" is on, returns "True" or "False"
  • event.isCtrlDown() - checks if "Ctrl" is on, returns "True" or "False"
  • event.isAltDown() - checks if  "Alt" is on, returns "True" or "False"




events.onMouseEvent(func)

This method handles mouse cursor movements.
It takes the handler function "func" as an argument, the function gets an event object "event" with different information for handling.

"event" - an event object with the following properties:

  • event.dx - delta change of coordinates in X-direction
  • event.dy - delta change of coordinates in Y-direction
  • event.dz - the value is always 0

events.onGotRibbon(func)

This event is triggered when the player gets a ribbon.
It takes the handler function "func" as an argument, input parameters of the function are *args, **kwargs.
The "args" argument takes a ribbon constant value.


events.onAchievementEarned(func)

This event is triggered when the player gets an achievement.
It takes the handler function "func" as an argument, input parameters of the function are *args, **kwargs.

Share this post


Link to post
Share on other sites
Administrator
10 posts
17 battles

PythonAPI - Flash

"Flash" methods are designed to work with the Flash part of the mod (a Main.swf file)

Available methods:

flash

  • flash.call(methodName, args = None)
  • flash.addExternalCallback(command, function)
  • flash.removeExternalCallback(command = None, function = None)
  • flash.loadFlashMod(modName)
  • flash.loadPyMod(modName)
  • flash.reloadMod(modName, needToReloadPy = False)
  • flash.unloadMod(modName, needToUnloadPy = False)
  • flash.getModsStatus()

flash.call(name, args)

This method calls a callback allowing you to call a function in the mod’s Flash file.

It takes the following arguments:

  • name – a name, callback key to which the function in the Flash part must be subscribed 
  • args – a list containing passed parameters (or an empty list without parameters) that will be passed to the called function for further handling

falsh_call.png


falsh.addExternalCallback(name, func)

This method adds a callback that signs and calls the function "func" handler in the Python part of the mod. This function accepts a call from the Flash part of the mod, similar to the previous method.

Input parameters of the function:

  • name - a name, callback key
  • func - a callback handler function

falsh_addExternalCallback.png


flash.removeExternalCallback(name, func)

This method removes a callback with a "name" identifier for the "func" handler function.

Input parameters of the function:

  • name - a name, callback key
  • func - a callback handler function

Note: When calling this function without parameters, the handler function list for the current mod will be fully cleared.


flash.loadFlashMod(modName)

This method loads the Flash part of the mod if it wasn’t loaded earlier or was unloaded.

The "modName" input argument is the name of the mod (the name of the folder containing the mod).


flash.loadPyMod(modName)

This method loads the Python part of the mod if it wasn’t loaded earlier or was unloaded. This method will also load the Flash part of the mod.

The modName input argument is the name of the mod.


flash.reloadMod(modName, needToReloadPy)

This method reloads the mod.

Input arguments:

  • modName – a name, mod identifier
  • needToReloadPy – if it is necessary to reload the Python part of the mod (False is a preset base value of the argument)

falsh_reloadMod.png


flash.unloadMod(modName, needToUnloadPy)

This method unloads (switches off) the mod.

Input arguments of the function:

  • modName – a name, mod name
  • needToUnloadPy - if it is necessary to unload the Python part of the mod (False is a base value of the argument)

flash.getModsStatus()

This method returns a dict containing keys (mod names) and values (their load statuses (True/False)).

falsh_getModsStatus.png

Share this post


Link to post
Share on other sites
Administrator
10 posts
17 battles

PythonAPI - Utils

"Utils" methods allow you to work with various additional functions.

Available methods:

utils

  • utils.getGameVersion()
  • utils.getModDir()
  • utils.stat(path)
  • utils.walk(top, topdown, followlinks)
  • utils.isFile(path)
  • utils.isDir(path)
  • utils.isPathExists(path)
  • utils.timeNowUTC()
  • utils.timeNow()
  • utils.jsonEncode(obj, skipkeys, ensure_ascii, check_circular, allow_nan, indent, separators, encoding, default, sort_keys)
  • utils.jsonDecode(s, encoding, parse_float, parse_int, parse_constant)

utils.getGameVersion()

This function returns the game version.

The returned value is the game version, line: 0, 5, 15, 123456


utils.getModDir()

This function returns an absolute path to the folder with the current mod.


utils.stat(path)

The method returns an object with attributes corresponding to attributes "os.stat(path)".
The input argument is the "path" to the file.

You can see full documentation on this function on the official Python website here: https://docs.python.org/2/library/os.html#os.stat


utils.walk(top, topdown=True, followlinks=False)

The method is similar to "os.walk(top, topdown=True, onerror=None, followlinks=False)" where:

  • "top" is a directory in the mod folder (if it exists) where the method will pass (see "C:\Games\World_of_Warships\res_mods\0.7.9.1\PnFMods\TestMod\testDir"),
  • "topdown" is a way of passing: "True" is top down (a base value), "False" is bottom up, generates file names in the directory tree moving along the tree down from the top or vice versa; for every  directory in the tree it is fixed in the top part of the directory switching on the top, and returns the following parameters:
  • "dirpath" is a string, a path to the directory
  • "dirnames" is a list, a list of sub-directory names in the directory "dirpath"
  • "filenames" is a list, a list of file names in this directory

You can see full documentation on this function on the official Python website here: https://docs.python.org/2/library/os.html#os.walk


utils.isFile(path)

The method is similar to "os.path.isfile(path)", it returns "True" if the file exists on the given "path".
The input argument is "path", a path to the file.

You can see full documentation on this function on the official Python website here: https://docs.python.org/2/library/os.path.html#os.path.isfile


utils.isDir(path)

The method is similar to "os.path.isDir(path)", it returns "True", if the directory exists on the given "path".
The input argument is "path", a path to the directory.

You can see full documentation on this function on the official Python website here : https://docs.python.org/2/library/os.path.html#os.path.isdir


utils.isPathExists(path)

The method is similar to "os.path.exists(path)", it returns "True", if the given "path" exists.
The input argument is "path", a path to the file/directory.

You can see full documentation on this function on the official Python website here: https://docs.python.org/2/library/os.path.html#os.path.exists


utils.timeNowUTC()

The method is similar to "datetime.datetime.utcnow()", it returns the current UTC and date.

You can see full documentation on this function on the official Python website here: https://docs.python.org/2/library/datetime.html#datetime.datetime.utcnow


utils.timeNow()

The method is similar to "datetime.datetime.now()", it returns the current time and date.

You can see full documentation on this function on the official Python website here: https://docs.python.org/2/library/datetime.html#datetime.datetime.now


utils.jsonEncode(obj)

The method is similar to "json.dumps(obj, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, cls=None, indent=None, separators=None, encoding="utf-8", default=None, sort_keys=False)" with corresponding base values.
The method serializes the object "obj" to a "JSON" line.

You can see full documentation on this function on the official Python website here: https://docs.python.org/2/library/json.html#json.dumps


utils.jsonDncode(s)

The method is similar to "json.loads(s)", it deserializes a "JSON" line to a Python object.

You can see full documentation on this function on the official Python website here: https://docs.python.org/2/library/json.html#json.loads

Share this post


Link to post
Share on other sites
Administrator
10 posts
17 battles

PythonAPI - Web

"Web" methods allow you to work with web resources.

Available methods:

web

  • web.getAllowedUrls()
  • web.addAllowedUrl(encodedUrl)
  • web.openUrl(url)
  • web.urlEncode(query, doseq=0)
  • web.urlQuote(s, safe='/') 

web.getAllowedUrls()

This function returns a list, a list of allowed URLs.


web.addAllowedUrl(encodedUrl)

This function adds a special encoded URL to the list of allowed URLs. You can request a special encoded URL from MedvedevTD by private messaging him at the official game forum.

The input arguments is encodedUrl, a special encoded URL.


web.openUrl(url)

The method is similar to "urllib2.urlopen(url, data=None)", it allows you to open a URL from the list of allowed URLs.
The input argument is an allowed URL.

You can see full documentation on this function on the official Python website here: https://docs.python.org/2/library/urllib2.html#urllib2.urlopen


web.urlEncode(query)

The method is similar to "urllib.urlencode(query, doseq=0)", it is used for coding a line in the format following the rules for data in queries.

You can see full documentation on this function on the official Python website here: https://docs.python.org/2/library/urllib.html#urllib.urlencode


web.urlQuote(s, safe='/')

The method is similar to "urllib.quote(string, safe)", it replaces all special symbols by strings "%nn". Numbers, Latin characters and underscore characters, dots and hyphens are not coded. Spaces are converted into the string "%20".
The input argument is "s", it’s the line where replacements are made, "safe" is symbols that cannot be converted.

You can see full documentation on this function on the official Python website here: https://docs.python.org/2/library/urllib.html#urllib.quote

Share this post


Link to post
Share on other sites
Administrator
10 posts
17 battles

PythonAPI - UserMusic

"UserMusic" methods allow you to work with ".mp3" audio files.

  • a basic path for a folder with audio files - "World_of_Warships\res_mods\<game_version>\userMusic", a basic folder "userMusic" is created manually, the folder name should be as specified above, otherwise (if a path or folder name is different from the basic one) the path is set by the method "userMusic.setPath" (see the description below)

userMusic_baseFolder.png

  • when forming the playlist all files (tuples) on the list are shuffled automatically
  • the playlist is looped; when the track list ends the player gets to the beginning of the list and continues playing tracks
  • playing of the list can be stopped this way: use "userMusic.clearPlaylist()" (described below) in the handler function "SetOnPlayTrackCallback" (described below), the playlist will be cleared, and the player will stop playing when it finishes playing the current track
  • to use your own sound files, flag the checkbox “Use your music” in the sound settings; otherwise the game music and user sound files overlap can result in conflicts and a game client crash

userMusic_soundCheckBox_en.png

Available methods:

userMusic

  • events.onPlayTrack(SetOnPlayTrackCallback)
  • userMusic.setPath(path)
  • userMusic.getPlaylist()
  • userMusic.getMediaFileList(path)
  • userMusic.addFiles(filelist)
  • userMusic.removeFiles(idsList)
  • userMusic.clearPlaylist()
  • userMusic.playNext()
  • userMusic.playPrevious()
  • userMusic.play(id)
  • userMusic.activate(state)

events.onPlayTrack(SetOnPlayTrackCallback)

This event is triggered when an audio file is played.
The method takes the handler function "SetOnPlayTrackCallback" that receives an index number of the playing track from the playlist as an input argument "arg".


userMusic.setPath(path)

The method sets a path to an audio file directory that is different from the basic one.
When the basic directory "World_of_Warships\res_mods\<game_version>\userMusic" is present, a new "path" to directory is added to the basic one to search for audio files to be played; added files are shuffled.
The input argument is "path", a path to a directory with audio files.


userMusic.getPlaylist()

The method returns a "list" of "tuples" with various information about "*.mp3" audio files (a path to the file, track name, singer, etc.) that will be played, where a tuple index on the playlist is an audio file index for the player.


userMusic.getMediaFileList(path)

The method returns a "list" with paths to "*.mp3" audio files.
The input argument is "path", a path to an audio file directory.


userMusic.addFiles(filelist)

The method adds a "list" with paths to "*.mp3" audio files to the main audio file playlist.
The input argument is "filelist", a list with paths to audio files.


userMusic.removeFiles(idsList)

This method removes selected audio files from the playlist (userMusic.getPlaylist).
It returns "True/False" if the file was/was not found in the list.  
The input argument "idsList" is a "list" with IDs of file indexes on the player playlist (starting from 0).


userMusic.clearPlaylist()

The method clears the audio file playlist (getPlaylist).


userMusic.playNext()

It plays the next track form the playlist.
It can start playing tracks from the second track on the playlist if the method "userMusic.play(id)" is not called; then the "id" basic index 
is id = 1.


userMusic.playPrevious()

It plays the previous track form the playlist.
It can start playing tracks from Track 0 on the playlist if the method "userMusic.play(id)" is not called; then the "id" basic index is id = 1.


userMusic.play(id)

The method allows you to play a selected track from the playlist.
The input argument "id" is a track index (tuple on the player list), the next track from the list is played, that is, 
if id = 0 then id = 1 is played if a track with this index is available; if the playlist contains no fewer than two files and this index is not available, then id = 1 is played.

userMusic_play_en.png


userMusic.activate(state)

The method activates/deactivates the audio file player. 
The input argument "state" takes on "True/False" (False is a base value), switching to False does not stop playing.

Share this post


Link to post
Share on other sites
Administrator
10 posts
17 battles

PythonAPI - Doc

"Dock" methods allow you to get additional game information in the port.

Available methods:

doc

  • dock.getActiveShipId()
  • dock.getShipInfoById(shipID)

dock.getActiveShipId()

This function returns the ID of the selected ship.


dock.getShipInfoById(shipID)

This function returns an object with information about the ship.  
The input parameter shipID is the ID of the selected ship.

Share this post


Link to post
Share on other sites
Administrator
10 posts
17 battles

FlashAPI

To create the Flash part of the mod, you need an ActionScript 3 IDE, you can use "FlashDevelop", "Adobe Flash Professional", "Adobe Flash Builder" and other editors.

Let’s create a new AS3 project. We call the main file "Main", it will have an extension "*.as” and we add an external SWC library (you can find an updated version in our resources) depending on the selected IDE.

FlashAPI_swc_library.png

(an example of adding it to Flash Builder)

Then we rework the script in the "Main.as" file of the project for our mod template.

FlashAPI_ModBase.png

We can create the Flash part of our mod now. As you see, our main class has the basic class "ModBase" contained in the added library, the Flash file of the mod will not work without it.

Share this post


Link to post
Share on other sites
Administrator
10 posts
17 battles

FlashAPI - DataBridgeModule

"Data Bridge Module" methods allow the mod to pass or receive data to/from the Python part of the mod.

Available methods:

gameAPI.data

  • gameAPI.data.call(methodName:String, params:Array):void
  • gameAPI.data.addCallBack(methodName:String, func:Function):void
  • gameAPI.data.removeCallBack(methodName:String = null, callBack:Function = null):void

gameAPI.data.call(methodName:String, params:Array):void

The method allows you to pass information to the Python part of the mod.
Input parameters:

  • "methodName" – a name, callback key the Python function is subscribed to (in Python - falsh.addExternalCallback(name, func) where "name" corresponds to "methodName")
  • "params" – an array of passed parameters.

gameAPI.data.addCallBack(methodName:String, func:Function):void

The method adds a callback to get information from Python (in Python - flash.call(name, args)) the Flash function is subscribed to.
Input parameters:

  • "methodName" – a name, callback key the function in the Flash part of the mod is subscribed to (Main.swf file)
  • "func" – a callback handler function

gameAPI.data.removeCallBack(methodName:String = null, callBack:Function = null):void

The method removes a callback the Flash function is subscribed to.
Input parameters
:

  • "methodName" - callback key the function in the Flash part of the mod is subscribed to (Main.swf file)
  • "callBack" - a callback handler function

Share this post


Link to post
Share on other sites
Administrator
10 posts
17 battles

FlashAPI - StageModule

"StageModule" methods allow you to work with "Stage".

Available methods:

gameAPI.stage

  • gameAPI.stage.addChild(child:displayObject)
  • gameAPI.stage.addChildAt(child:displayObject, index:int)
  • gameAPI.stage.removeChild(child:displayObject)
  • gameAPI.stage.removeChildAt(index:int)
  • gameAPI.stage.width()
  • gameAPI.stage.height()

gameAPI.stage.addChild(child:displayObject)

It works in a way similar to the "addChild" method, it adds a "displayObject" to the "Stage" to visualize the object.
The input argument "child" is a Flash object that is being created.


gameAPI.stage.addChildAt(child:displayObject, index:int)

Like the "addChildAt" method, it adds a DispalyObject to a certain layer of the Stage.
The input arguments: "child" - a Flash object that is being created; index - an indexing number of the layer where a DisplayObject should be added.


gameAPI.stage.removeChild(child:displayObject)

The method removes a DispalyObject from the Stage.
The input argument "child" is a DisplayObject that should be removed from the Stage.


gameAPI.stage.removeChildAt(index:int)

The method removes the top layer from the Stage.
The input argument "index" is an indexing number of the layer where a DisplayObjec
t should be removed.


gameAPI.stage.width()

The method returns the Stage width. 
The returned value is a "Number" type of data.


gameAPI.stage.height()

The method returns the Stage height.
The returned value is a "Number" type of data.

Share this post


Link to post
Share on other sites
Guest
This topic is now closed to further replies.
Sign in to follow this  

×