Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
98 lines (88 sloc) 5.27 KB

Paracraft Filters

Filters are integration points in Paracraft, which allows paracraft mod/app developers to customize the application cooperatively. Filters is a design pattern of input-output chains. Please see script/ide/System/Core/Filters.lua for details.

One can search for GameLogic.GetFilters():apply_filters, such as below:

xmlRoot = GameLogic.GetFilters():apply_filters("block_types", xmlRoot);

How to Use Filters In Paracraft

There is a global function called GameLogic.GetFilters() which returns the primary filter in Paracraft. One should add_filter before apply_filter, so one should call add_filter code as early as possible to install all filters used by your plugin, such as when Mod is initialized or application just started.

The following example code, registered a new item.

-- register a new block item, id < 512 is internal blocks, which is not recommended to modify. 
GameLogic.GetFilters():add_filter("block_types", function(xmlRoot) 
	local blocks = commonlib.XPath.selectNode(xmlRoot, "/blocks/");
	if(blocks) then
		blocks[#blocks+1] = {name="block", attr={
			id = 512, threeSideTex = "true",
			text = "Demo Item", name = "DemoItem",
			obstruction="true", solid="true", cubeMode="true",
		LOG.std(nil, "info", "DemoItem", "a new block is registered");
	return xmlRoot;

List of Paracraft Filters

This givens an overview of filters in paracraft. Please search the source code of paracraft for how to use these filters.

  • block related:

    • "block_type", xmlRoot: for registering new item type
    • "block_list", xmlRoot: for registering new item type in builder GUI
    • "block_types_template", xmlRoot: for registering or modify block type's template
    • "register_item": for registering new item type in client
  • user input mouse and keyboard:

    • "DefaultContext", context, mode: getting the default scene context for user input
  • GUI:

    • "InitDesktop", bSkipDefaultDesktop: called to init the default desktop UI
    • "ActivateDesktop", bIgnoreDefaultDesktop, mode: called when desktop mode is changed. This is the place to initialize your custom GUI.
    • "show", name, bIsShow: hook /show name command to display a custom gui via command
    • "cmd_open_url", url, options: hook /open url command to display a custom url via command
    • "InternetLoadWorld.ShowPage", bEnable, bShow: whether to show the default load world window. We can use this filter to replace the default load world window.
    • "SaveWorldPage.ShowSharePage", bEnable: We can use this filter to replace the default share world window.
    • "ShowExitDialog", {text, callback}: use this filter to display a dialog when user exits the application, return nil if one wants to replace the implementation.
    • "show_custom_create_new_world", behavior("show" or "close"):use this filter to customize your CreateNewWorld page.
    • "show_custom_download_world", behavior("show" or "close"), url:use this filter to customize your DownloadWorld page.
  • world:

    • "PlayerHasLoginPosition", nil, x,y,z: called whenever the player is at its spawn position in both local or remote world.
    • "BeforeSetSpawnPoint", {x,y,z}: before player spawn point is set
    • "SetSpawnPoint", nil, x,y,z: whenever the player spawn point is set.
    • "before_generate_chunk", x, z:
    • "after_generate_chunk", x, z:
    • "load_world_info", worldInfo, node:
    • "save_world_info", worldInfo, node:
    • "OnBeforeLoadBlockRegion", true, x, y:
    • "OnSaveBlockRegion", true, region_x, region_z, "region.xml":
    • "OnLoadBlockRegion", true, x, y:
    • "OnUnLoadBlockRegion", true, x, y:
    • "worldFileChanged", msg:
    • "GetWorldGeneratorClass", generator, name: get world generator by name filter. Use this to add custom world generators
    • "OnClickCreateWorld"
    • "OnWorldLoaded" when world is successfully loaded
    • "OnWorldUnloaded" when world is unloaded
  • global:

    • "register_classes_into_sandbox_api", additionalEnv:
    • "desktop_menu", menu_items:
    • "new_item", itemStackArray, self:
    • "item_client_new_item_type_added", block_id, item:
    • "user_event_stat", category, action, value, label:
  • file exporters:

    • "file_exported", id, filename:
    • "GetExporters", exporters: file exporters
    • "export_to_file", filename:
    • "select_exporter", id:
  • command:

    • "register_command": register additional commands
  • networking:

    • "handleLogin", packet_login: whenever client received confirmed login packet from server.
    • "entity_player_mp_other_entity_action_state_updated", entity_player_mp_other: after every time entity action state get updated for EntityPlayerMPOther
    • "entity_player_mp_entity_action_state_updated", entity_player_mp: after every time entity action state get updated for EntityPlayerMP
  • movie:

    • "pop_movie_mode", lastMode:when the movie mode is popped
  • downloadFile:

    • "downloadFile_notify", downloadState(0:downloading, 1:complete, 2:terminated),text(downloadFile text tips),currentFileSize, totalFileSize
  • urlprotocol:

    • "load_world_from_cmd_precheck", hijacking cmdline_world, return a custom path

Adding New filters

If you want to add new filters to paracraft, you can either start a new issue on github or send us a pull request with your code.